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1. Introduction 


The X Window System (or simply X 

developed at MIT has achieved fairly widespread popularity recently, particularly in the Unix 4 
community. In this paper, we present an overview of X, focusing on the system substrate and the 
low-level facilities provided to build applications and to manage the desktop. In X, this base window 
system provides high-performance graphics to a hierarchy of resizable windows. Rather than mandating 
a particular user interface, X provides primitives to support several policies and styles. Unlike most 
window systems, the base system in X is defined by a network protocol: asynchronous stream-based 
inter-process communication replaces the traditional procedure call or kernel call interface. An 
application can utilize windows on any display in a network in a device-independent, network-transparent 
fashion. Interposing a network connection greatly enhances the utility of the window system, without 
significantly affecting performance. The performance of existing X implementations is comparable to 
contemporary window systems, and in general is limited by display hardware rather than network 
communication. For example, 19500 characters per second and 3500 short vectors per second are 
possible on Digital Equipment Corporation’s VAXStation-ll/GPX, both locally and over a local area 
network, and these figures are very close to the limits of the display hardware. 

X is the result of the simultaneous need for a window system from two separate groups at MIT. In the 
summer of 1984, the Argus system [13] at the Laboratory for Computer Science needed a debugging 
environment for multi-process distributed applications, and a window system seemed the only viable 
solution. Project Athena [3] was faced with dozens, and eventually thousands of workstations with bitmap 
displays, and needed a window system to make the displays useful. Both groups were starting with the 
Digital VS100 display [11] and VAX hardware, but it was clear at the outset that other architectures and 
displays had to be supported. In particular, equal numbers of IBM workstations with bitmap displays of 
unknown type were expected eventually within Project Athena. Portability was therefore a goal from the 
start. Although all of the initial implementation work was for Berkeley Unix, it was clear that the network 
protocol should not depend on aspects of the operating system. 

The name X derives from the lineage of the system. At Stanford University, Paul Asente and Brian 
Reid had begun work on the W window system [2], as an alternative to VGTS[10, 18] for the V 
system [4], Both VGTS and W allow network-transparent access to the display, using the synchronous V 
communication mechanism. Both systems provide "text" windows for ASCII terminal emulation. VGTS 
provides graphics windows driven by fairly high-level object definitions from a structured display file; W 
provides graphics windows based on a simple display-list mechanism, with limited functionality. We 
acquired a Unix-based version of W for the VS100 (with synchronous communication over TCP [21]) 
done by Asente and Chris Kent at Digital’s Western Research Laboratory. From just a few days of 
experimentation, it was clear that a network-transparent hierarchical window system was desirable, but 
that restricting the system to any fixed set of application-specific modes was completely inadequate. It 
was also clear that, although synchronous communication was perhaps acceptable in the V system (due 
to very fast networking primitives), it was completely inadequate in most other operating environments. X 
is our "reaction" to W. The X window hierarchy comes directly from W, although numerous systems have 
been built with hierarchy in at least some form [8, 12, 25, 28, 30, 31, 32, 33, 29], The asynchronous 
communication protocol used in X is a significant improvement over the synchronous protocol used in W, 


4 Unix is a trademark of AT&T Bell Laboratories. 
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but is very similar to that used in Andrew [7, 16]. X differs from all of these systems in the degree to 
which both graphics functions and "system" functions are pushed back (across the network) as 
application functions, and in the ability to transparently tailor desktop management. 

The next section presents several high-level requirements that we believe a window system must 
satisfy to be a viable standard in a network environment, and indicates where the design of X fails to meet 
some of these requirements. In Section 3 we describe the overall X system model, and the effect of 
network-based communication on that model. Section 4 describes the structure of windows, and the 
primitives for manipulating that structure. Section 5 explains the color model used in X, and Section 6 
presents the text and graphics facilities. Section 7 discusses the issues of window exposure and refresh, 
and their resolution in X. Section 8 deals with input event handling. In Section 9, we describe the 
mechanisms for desktop management. 

This paper describes the version 5 of X that is currently in widespread use. The design of this version is 
inadequate in several respects. With our experience to date, and encouraged by the number of 
universities and manufacturers taking a serious interest in X, we have designed a new version that should 
satisfy a significantly wider community. Section 10 discusses a number of problems with the current X 
design, and gives a general idea of what changes are contemplated. 

2. Requirements 

A window system contains many interfaces. A programming interface is a library of routines and types 
provided in a programming language for interacting with the window system. Both low-level (e.g., line 
drawing) and high-level (e.g., menus) interfaces are typically provided. An application interface is the 
mechanical interaction with the user and the visual appearance that is specific to the application. A 
management interface is the mechanical interaction with the user dealing with overall control of the 
desktop and the input devices. The management interface defines how applications are arranged and 
rearranged on the screen, and how the user switches between applications; an individual application 
interface defines how information is presented and manipulated within that application. The user interface 
is the sum total of all application and management interfaces. 

Besides applications, we distinguish three major components of a window system. The window 
manage i 6 implements the desktop portion of the management interface; it controls the size and 
placement of application windows, and also may control application window attributes such as titles and 
borders. The input manager implements the remainder of the management interface; it controls which 
applications see input from which devices (e.g., keyboard and mouse). The base window system is the 
substrate on which applications, window managers, and input managers are built. 

In this paper we are concerned with the base window system of X, with the facilities it provides to build 
applications and managers. The following requirements on the base window system crystallized during 
the design of X (a few were not formulated until late in the design process): 

1. The system should be implementable on a variety of displays. 


5 Version 10. 

6 Some people use this term for what we call the base window system; that is not the meaning here. 


The system should work with nearly any bitmap display, and a variety of input devices. Our 
design focused on workstation-class display technology likely to be available in a university 
environment over the next few years. At one end of the spectrum is a simple frame buffer 
and monochrome monitor, driven directly by the host CPU with no additional hardware 
support. At the other end of the spectrum is a multi-plane display with color monitor, driven 
by a high-performance graphics co-processor. Input devices such as keyboards, mice, 
tablets, joysticks, light pens, and touch screens should be supported. 

2. Applications must be device independent. 

There are several aspects to device independence. Most importantly, it must not be 
necessary to rewrite, recompile, or even relink an application for each new hardware 
display. Nearly as important, every graphics function defined by the system should work on 
virtually every supported display; the alternative, which is to use GKS-style inquire 
operations [9] to determine the set of implemented functions at run-time, leads to tedious 
case analysis in every application, and to inconsistent user interfaces. A third aspect of 
device independence is that, as far as possible, applications should not need dual control 
paths to work on both monochrome and color displays. 

3. The system must be network transparent: an application running on one machine must be 
able to utilize a display on some other machine. The two machines should not have to have 
the same architecture or operating system. 

There are numerous examples of why this important: a compute-intensive VLSI design 
program executing on a mainframe, but displaying results on a workstation; an application 
distributed over several stand-alone processors, but interacting with a user at a workstation; 
a professor running a program on one workstation, presenting results simultaneously on all 
student workstations. 

In a network environment, there are certain to be applications that must run on particular 
machines or architectures. Examples include proprietary software, applications depending 
on specific architectural properties, and programs manipulating large databases. Such 
applications still should be accessible to all users. In a truly heterogeneous environment, 
not all programming languages and programming systems are supported on all machines, 
and it is very undesirable to have to write an interactive front end in multiple languages in 
order to make the application generally available. With network-transparent access, this is 
not necessary; a single front end written in the same language as the application suffices. 

One might think that remote display will be extremely infrequent, and that performance 
therefore is much less important than for local display. Experience at MIT, however, 
indicates that many users routinely make use of the remote display capabilities in X, and 
that the performance of remote display is quite important. The desktop display, although 
physically connected to a single computer, is used as a true network virtual terminal-, 
indeed, the idea of an X server (see the next section) built into a Blit-like terminal [20] is an 
intriguing one. 

4. The system must support multiple applications displaying concurrently. 

For example, it should be possible to display a clock with a sweep second hand in one 
window, while simultaneously editing a file in another window. 

5. The system should be capable of supporting many different application and management 
interfaces. 

No single user interface is "best"; different communities have radically different ideas about 
user interfaces. Even within a single community, "experts" and "novices" place different 
demands on an interface. Rather than mandating a particular user interface, the base 
window system should support a wide range of interfaces. 

To achieve this, the system must provide hooks (mechanism) rather than religion (policy). 
For example, since menu styles and semantics vary dramatically among different user 



interfaces, the base window system must provide primitives from which menus can be built, 
rather than just providing a fixed menu facility. 

The system should be designed in such a way that it is possible to implement management 
policy both external to the base window system and external to applications. Applications 
should be largely independent of management policy and mechanism; applications should 
react to management decisions, rather than directing those decisions. For example, an 
application needs to be informed when one of its windows is resized, and should react by 
reformatting the information displayed, but involvement of the application should not be 
required in order for the user to change the size. Making applications management- 
independent, as well as device-independent, facilitates the sharing of applications between 
diverse cultures. 

6. The system must support overlapping windows, including output to partially obscured 
windows. 

This is in some sense a by-product of the previous requirement, but is important enough to 
merit explicit statement. Not all user interfaces allow windows to overlap arbitrarily. 
However, even interfaces that do not allow application windows to overlap typically provide 
some form of pop-up menu that overlaps application windows. If such menus are built from 
windows, then support for overlapping windows must exist. 

7. The system should support a hierarchy of resizable windows, and an application should be 
able to use many windows at once. 

Subwindows provide a clean, powerful mechanism for exporting much of the basic system 
machinery back to the application for direct use. Many applications make use of their own 
window-like abstractions; some even implement what is essentially another window system, 
nested within the "real" window system. It is important to support arbitrary levels of nesting. 

What is viewed as a single window at one abstraction level may well require multiple 
subwindows at a lower level. By providing a true window hierarchy, application windows 
can be implemented as true windows within the system, freeing the application from 
duplicating machinery such as clipping and input control. 

8. The system should provide high-performance, high-quality support for text, 2-D synthetic 
graphics, and imaging. 

The base window system must provide "immediate" or "transparent" graphics: the 
application describes the image precisely, and the system does not attempt to second- 
guess the application. The use of high-level models, whereby the application describes 
what it wants in terms of fairly abstract objects and the system determines how best to 
render the image, cannot be imposed as the only form of graphics interface. Such models 
generally fail to provide adequate support for some important class of applications, and 
different user communities tend to have strong opinions about which model is "best". High- 
level models are extremely important to provide, but they should be built in layers on top of 
the base window system. 

Support for 3-D graphics is not listed as a requirement, but this is not to say it is 
unimportant. We simply have not considered 3-D graphics, due to lack of expertise and 
lack of time. 

9. The system should be extensible. 

For example, the core system may not support 3-D graphics, but it should be possible to 
extend the system with such support. The extension mechanism should allow communities 
to extend the system non-cooperatively, yet allow such independent extensions to be 
merged gracefully. 

We believe that a window system must satisfy these requirements to be a viable standard in an 
environment of high-performance workstations and mainframes connected via high-performance local 
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area networks. X satisfies most of these requirements, but currently fails to satisfy a few due to practical 
considerations of staffing and time constraints: the design and much of the implementation of the base 
window system was to be handled solely by the first author; it was important to get a working system up 
fairly quickly; and the immediate applications only required relatively simple text and graphics support. As 
a result, X is not designed to handle high-end color displays or to deal with input devices other than a 
keyboard and mouse; some support for high-quality text and graphics is missing; X only provides support 
for one class of management policy; and no provision has been made for extensions. As discussed in 
Section 10, these and other problems are being addressed in a redesign of X. 


3. System Model 

The X window system is based on a client-server model; this model follows naturally from requirements 
two and three in the previous section. For each physical display, there is a controlling server. A client 
application and a server communicate over a reliable duplex (8-bit) byte stream. A simple block stream 
protocol is layered on top of the byte stream. If the client and server are on the same machine, the 
stream is typically based on a local inter-process communication (IPC) mechanism, and otherwise a 
network connection is established between the pair. Requiring nothing more than a reliable duplex byte 
stream (without urgent data) for communication makes X usable in many environments. For example, the 
X protocol can be used over TCP [21], DECnet [36], and Chaos [15]. 

Multiple clients can have connections open to a server simultaneously, and a client can have 
connections open to multiple servers simultaneously. The essential tasks of the server are to multiplex 
requests from clients to the display, and demultiplex keyboard and mouse input back to the appropriate 
clients. Typically, the server is implemented as a single sequential process, using round-robin scheduling 
among the clients, and this centralized control trivially solves many synchronization problems; however, a 
multi-process server has also been implemented. Although one might place the server in the kernel of 
the operating system in an attempt to increase performance, a user-level server process is vastly easier 
to debug and maintain, and performance under Unix in fact does not seem to suffer. Similar performance 
results have been obtained in Andrew [7], Various tricks are used in both clients and server to optimize 
performance, principally by minimizing the number of operating system calls [6], 

The server encapsulates the base window system. It provides the fundamental resources and 
mechanisms, and the hooks required to implement various user interfaces. All device dependencies are 
encapsulated by the server; the communication protocol between clients and the server is device 
independent. By placing all device dependencies on one end of a network connection, applications are 
truly device independent. The addition of a new display type simply requires the addition of a new server 
implementation; no application changes are required. Of course, the server itself is designed as device 
independent code layered on top of a device dependent core, so only the "back end" of the server need 
be reimplemented for each new display. 7 


7 A back end has been implemented using a programming interface to X itself, such that a complete “recursive" X server executes 
inside a window of another X server. 
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Figure 2-1 : System Structure 
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3.1. Network Considerations 

It is extremely important for the server to be robust with respect to client failures. The server, and the 
network protocol, must be designed so that the server never trusts clients to provide correct data. As a 
corollary, the protocol must be designed in such a way that, if the server ever has to wait for a response 
from a client, it must be possible to continue servicing other clients. Without this property, a buggy client 
or a network failure could easily cause the entire display to freeze up. 

Byte ordering is a standard problem in network communication: when a 16-bit or 32-bit quantity is 
transmitted over an 8-bit byte stream, is the most significant byte transmitted first (big-endian byte order) 
or is the least significant byte transmitted first (little-endian byte order)? Some machines with byte- 
addressable memory use big-endian order internally, and others use little-endian order. If a single order 
is chosen for network communication, some machines will suffer the overhead of swapping bytes, even 
when communicating with a machine using the same internal byte order. Such an approach also means 
that both parties in the communication must worry about byte order. 

The X protocol uses a different approach. The server is designed to accept both big-endian and 
little-endian connections. For example, using TCP this is accomplished by having the server listen on two 
distinct ports: little-endian clients connect to the server on one port, and big-endian clients connect on the 
other. Clients always transmit and receive in their native byte order. The server alone is responsible for 
byte swapping, and byte swapping only occurs between dissimilar architectures. This eliminates the byte 
swapping overhead in the most common situations, and greatly simplifies the building of client-side 
interface libraries in various programming languages. X is not unique in its use of this trick; the current 
VGTS implementation uses the same trick, and similar protocol optimizations have been used in various 
network-based applications. 

Another potential problem in protocol design is word alignment. In particular, some architectures 
require 16-bit quantities to be aligned on 16-bit boundaries and 32-bit quantities to be aligned on 32-bit 
boundaries in memory. To allow efficient implementations of the protocol across a spectrum of 16-bit and 
32-bit architectures, the protocol is defined to consist of blocks that are always multiples of 32 bits, and 
each 16-bit and 32-bit quantity within a block is aligned on 16-bit and 32-bit boundaries, respectively. 

X is designed to operate in an environment where the inter-process communication round-trip time is 
between 5 and 50 milliseconds, both for local and for network communication. We also assume that data 
transmission rates are comparable to display rates; for example, to transmit and display 5000 characters 
per second, a data rate of approximately 50Kb (kilobits per second) will be needed, and to transmit and 
display 20000 characters per second, a data rate of approximately 200Kb will be needed. Networks and 
protocol implementations with these characteristics are now quite commonplace. For example, 
workstations running Berkeley Unix, connected via 10Mb (megabits per second) local area networks, 
typically have round-trip times of 15 to 30 milliseconds, and data rates of 500Kb to 1Mb. 

The round-trip time is important in determining the form of the communication protocol. The most 
common communication will be text and graphics requests sent from a client to the server. Examples of 
individual requests might be to draw a string of text or to draw a line. Such requests could be sent either 
synchronously, in which case the client sends a request only after receiving a reply from the server to the 
previous request, or they could be sent asynchronously, without the server generating any replies. 
However, since the requests are sent over a reliable stream, they are guaranteed to arrive, and arrive in 
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order, so replies from the server to graphics requests serve no useful purpose. Moreover, with round-trip 

times over 5 milliseconds, output to the display must be asynchronous, or it will be impossible to drive 
high-speed displays adequately. For example, at 80 characters per request and a 25 millisecond round- 
trip time, only 3200 characters per second can be drawn synchronously, whereas many hardware devices 
are capable of displaying between 5000 and 30000 characters per second. 

Similarly, polling the server for keyboard and mouse input would be unacceptable in many applications, 
particularly those written in sequential languages. For example, an application attempting to provide 
real-time response to input has to poll periodically for input during screen updates. For an application 
with a single thread of control, this effectively results in synchronous output, and consequent performance 
loss. Ffence, input must be generated asynchronously by the server, so that applications need at most 
perform local polling. 

The round-trip time is also important in determining what user interfaces can be supported without 
embedding them directly in the server. The most important concern is whether remote, application-level 
mouse tracking is feasible. By tracking, we do not mean maintaining the cursor image on the screen as 
the user moves the mouse; that function is performed autonomously by the X server, often directly in 
hardware. Rather, applications track the mouse by animating some other image on the screen in real 
time as the mouse moves. For round-trip times under 50 milliseconds, tracking is perfectly reasonable, 
driven either by motion events generated by the server or by continuous polling from the application. With 
a refresh occurring up to 30 times every second, remote tracking is demonstrably "instantaneous" with 
mouse motion. 

For tracking to be effective, however, relatively little time can be spent updating the display at each 
movement, so typically only relatively small changes can be made to the screen while tracking. This is 
certainly the case for common operations, such as rubber banding window outlines and highlighting menu 
items. It might be argued that the ability to run application-specific code in the server is required for 
acceptable hand-eye coordination during complex tracking. For example, NeWS [27] provides such a 
mechanism in a novel way. Flowever, we are not convinced there are sufficient benefits to justify such 
complexity. Complex tracking typically is bound up intimately with application-specific data structures and 
knowledge representations, and such information is used by the "back end" of the application as well as 
the "front end”. In a distributed system it is folly to believe that applications will download large front ends 
into a server; communication round-trip times are a reality that cannot be escaped. 

3.2. Resources 

The basic resources provided by the server are windows, fonts, mouse cursors, and off-screen images; 
later sections describe each of these. Clients request creation of a resource by supplying appropriate 
parameters (such as the name of the font); the server allocates the resource and returns a 31-bit unique 
identifier used to represent it. The use and interpretation of a resource identifier is independent of any 
network connection. Any client that knows (or guesses) the identifier for a resource can use and 
manipulate the resource freely, even if it was created by another client. This capability is required to allow 
window managers to be written independently of applications, and to allow multi-process applications to 
manipulate shared resources. Flowever, to avoid problems associated with clients that fail to clean up 
their resources at termination (which is all too common in operating systems where users can unilaterally 
abort processes), the maximum lifetime of a resource is always tied to the connection over which it was 
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created. Thus, when a client terminates, all of the resources it created are destroyed automatically. 

Access control is performed only when a client attempts to establish a connection to the server; once 
the connection is established the client can freely manipulate any resource. Since accidental 
manipulation of some other client’s resource is extremely unlikely (both in theory and in practice), we 
believe introducing access control on a per-resource basis would only serve to decrease performance, 
not to significantly increase security or robustness. The current access control mechanism is based 
simply on host network addresses, as this information is provided by most network stream protocols, and 
there seems to be no widely used or even widely available user-level authentication mechanism. Host- 
based access control has proven to be marginally acceptable in a workstation environment, but is rather 
unacceptable for time-shared machines. 8 

Each client-generated protocol request is a simple data block consisting of an opcode, some number of 
fixed-length parameters, and possibly a variable-length parameter. For example, to display text in a 
window, the fixed-length parameters include the drawing color and the identifiers for the window and the 
font, and the variable-length parameter is the string of characters. All operations on a resource explicitly 
contain the identifier of the resource as a parameter. In this way, an application can multiplex use of 
many windows over a single network connection. This multiplexing makes it easy for the client to control 
the time-order of updates to multiple windows. Similarly, each input event generated by the server 
contains the identifier of the window in which the event occurred. Multiplexing over a single stream allows 
the client to act on events from multiple windows in correct time order; timestamps alone are inadequate 
without strong guarantees from the stream mechanism. 

Numerous Unix-based window systems [14, 16, 17, 19, 28, 30, 33] use file or channel descriptors to 
represent windows; window creation involves an interaction with the operating system, which results in 
the creation of such a descriptor. Typically, this means the window cannot be named (and hence cannot 
be shared) by programs running on different machines, and perhaps not even by programs running on 
the same machine. More serious, there is often a severe restriction on the number of active descriptors a 
process may have: 20 on older systems and usually 64 on newer systems. The use of 50 or more 
windows (albeit nested inside a single top-level window) is quite common in X applications. The use of a 
single connection, over which an arbitrary number of windows can be multiplexed, is clearly a better 
approach. 

4. Window Hierarchy 

The server supports an arbitrarily branching hierarchy of rectangular windows. At the top is the root 
window, which covers the entire screen. The top-level windows of applications are created as 
subwindows of the root window. The window hierarchy models the now-familiar "stacks of papers" 
desktop. For a given window, its subwindows can be stacked in any order, with arbitrary overlaps. When 
window W1 partially or completely covers window W2, we say that W1 obscures W2. This relationship is 
not restricted to siblings; if W1 obscures W2, then W1 may also obscure subwindows of W2. A window 
also obscures its parent. Window hierarchies never interleave; if window W1 obscures sibling window 
W2, then subwindows of W2 never obscure W1 or subwindows of W1. A window is not restricted in size 
or placement by the boundaries of its parent, but a window is always visibly clipped by its parent: portions 


8 lt is interesting that professors at MIT have argued vociferously to disable all access control. 



11 


of the window that extend outside the boundaries of the parent are never displayed, and do not obscure 
other windows. Finally, a window can be either mapped or unmapped. An unmapped window is never 
visible on the screen; a mapped window can only be visible if all of its ancestors are also mapped. 

Output to a leaf window (one with no subwindows) is always clipped to the visible portions of the 
window; drawing on such a window never draws into obscuring windows. Output to a window that 
contains subwindows can be performed in two modes. In clipped mode the output is clipped normally by 
all obscuring windows (including subwindows), but in draw-through mode the output is not clipped by 
subwindows. For example, draw-through mode is used on the root window during window management, 
tracking the mouse with the outline of a window to indicate how the window is to be moved or resized. If 
clipped mode were used instead, the entire outline would not be visible. 

The coordinate system is defined with the X axis horizontal and the Y axis vertical. Each window has 
its own coordinate system, with the origin at the upper left corner of the window. Having per-window 
coordinate systems is crucial, particularly for top-level windows; applications are almost always designed 
to be insensitive to their position on the screen, and having to worry about race conditions when moving 
windows would be a disaster. The coordinate system is discrete: each pixel in the window corresponds to 
a single unit in the coordinate system, with coordinates centered on the pixels, and all coordinates are 
expressed as integers in the protocol. We believe fractional coordinates are not required at the protocol 
level for the raster graphics provided in X (see section 6), although they may be required for high-end 
color graphics, such as anti-aliasing. The aspect ratio of the screen is not masked by the protocol, since 
we believe that most displays have a one to one aspect ratio; in this regard X is arguably device 
dependent. 

Although the coordinate system is discrete at the protocol level, continuous or alternate-origin 
coordinate systems certainly can be used at the application level, but client-side libraries must eventually 
translate to the discrete coordinates defined by the protocol. In this way, we can ignore the many 
variations in floating-point (or even fixed-point) formats among architectures. Further, the coordinates can 
be expressed in the protocol as 1 6-bit quantities, which can be manipulated efficiently in virtually every 
machine/display architecture, and which minimizes the number of data bytes transmitted over the 
network. The use of 1 6-bit quantities does have a drawback, in that some applications (particularly CAD 
tools) like to perform zoom operations simply by scaling coordinates and redrawing, relying on the window 
system to clip appropriately. Since scaling quickly overflows 16 bits, additional clipping must be 
performed explicitly by such applications. 

A window can optionally have a border, a shaded outer frame maintained explicitly by the X server. 
The origin of the window’s coordinate system is inside the border, and output to the window is clipped 
automatically so as not to extend into the border. The presence of borders slightly complicates the 
semantics of the window system; for simplicity we will ignore them in the remainder of this paper. 

The basic operations on window structure are straightforward. An unmapped window is created by 
specifying the parent window, the position within the parent of the upper left corner of the new window, 
and the width and height (in coordinate units) of the new window. A window can be destroyed, in which 
case all windows below it in the hierarchy are also destroyed. A window can be mapped and unmapped, 
without changing its position. A window can be moved and resized, including being moved and resized 
simultaneously. A window can also be "depthwise" raised to the top or lowered to the bottom the stack 
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with respect to its siblings, without changing its coordinate position. Currently mapping or configuring a 
window forces the window to be raised. This restriction appeared to simplify the server implementation, 
but also happened to match the basic management interface we expected to build. This restriction will be 
eliminated in the next version. 

The windows described above are the usual opaque windows. X also provides transparent windows. 
A transparent window is always invisible on the screen, and does not obscure output to, or visibility of, 
other windows. Output to a transparent window is clipped to that window, but is actually drawn on the 
parent window. Thus, for output, a transparent window is simply a clipping rectangle that can be applied 
to restrict output within a (parent) window. Input processing for transparent and opaque windows is 
identical, as described in Section 8. In Section 10 we will argue that most uses of transparent windows 
are better satisfied with other mechanisms. Therefore, for simplicity, we will ignore transparent windows 
in the rest of this paper. 

The X server is designed explicitly to make windows inexpensive. Our goal was to make it reasonable 
to use windows for such things as individual menu items, buttons, even individual items in forms and 
spreadsheets. As such, the server must deal efficiently with hundreds (though not necessarily thousands) 
of windows on the screen simultaneously. Experience with X has shown that many implementors find this 
capability extremely useful. 

5. Color 

The screen is viewed as two dimensional, with an N-bit pixel value stored at each coordinate. The 
number of bits in a pixel value, and how a value translates into a color, depends on the hardware. X is 
designed to support two types of hardware: monochrome and pseudo-color. A monochrome display has 
one bit per pixel, and the two values translate into black and white. Pseudo-color displays typically have 
between four and twelve bits per pixel; the pixel value is used as an index into a color map, yielding red, 
green, and blue intensities. The color map can be changed dynamically, so that a given pixel value can 
represent different colors overtime. Gray-scale is viewed as a degenerate case of pseudo-color. 

We desire a design matching most display hardware, while abstracting differences in such a way that 
programmers do not have to double or triple-code their applications to cover the spectrum. We also want 
multiple applications to coexist within a single color map, so that applications always show true color on 
the screen. To allow this, and to keep applications device independent, pixel values should not be coded 
explicitly into applications. Instead, the server must be responsible for managing the color map, and color 
map allocation must be expressed in hardware-independent terms. 

All graphics operations in X are expressed in terms of pixel values. For example, to draw a line, one 
specifies not only the coordinates of the end-points but the pixel value with which to draw the line. (Logic 
functions and plane-select masks are also specified, as described in Section 6.) On a monochrome 
display, the only two pixel values are zero and one, which are (somewhat arbitrarily) defined to be black 
and white, respectively. On a pseudo-color display, pixel values zero and one are pre-allocated by the 
server, for use as "black" and "white", so that monochrome applications display correctly on color 
displays. Of course, the actual colors need not be black and white, but can be set by the user. 

There are two ways for a client to obtain pixel values. In the simplest request, the client specifies red, 
green, and blue color values, and the server allocates an arbitrary pixel value and sets the color map so 
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the pixel value represents the closest color the hardware can provide. The color map entry for this pixel 
value cannot be changed by the client, so if some other client requests an equivalent color, the server is 

free to respond with the same pixel value. Such sharing is important in maximizing use of the color map. 
To isolate applications from variations in color representation among displays (due, for example, to the 
standard of illumination used for calibration), the server provides a color database which clients can use 
to translate string names of colors into red, green, and blue values tailored for the particular display. 

The second request allocates writable map entries. This mechanism was designed explicitly for X; we 
are not aware of a comparable mechanism in any other window system. The client specifies two 
numbers, C and P, with C positive and P non-negative; the request can be expressed as "allocate C 
colors and P planes". The total number of pixel values allocated by the server is C*2 P . The values 
passed back to the client consist of C base pixel values, and a plane mask containing P bits. None of the 
base pixel values have any one bits in common with the plane mask, and the complete set of allocated 
pixel values is obtained by combining all possible combinations of one bits from the plane mask with each 
of the base pixel values. The client can optionally require the P planes to be contiguous, in which case all 
Pbits in the plane mask will be contiguous. 

There are three common uses of this second request. One is simply to allocate a number of 
"unrelated" pixel values; in this case, Pwill be zero. A second use is in imaging applications, where it is 
convenient to be able to perform simple arithmetic on pixel values. In this case, a contiguous block of 
pixel values is allocated by setting C to one and P to the log (base 2) of the number of pixel values 
required, and requesting contiguous allocation. Arithmetic on the pixel values then requires at most some 
additional shift and mask operations. 

A third form of allocation arises in applications that want some form of overlay graphics, such as 
highlighting or outlining regions. Here the requirement is to be able to draw and then erase graphics 
without disturbing existing window contents. For example, suppose an application typically uses four 
colors, but needs to be able to overlay a rectangle outline in a fifth color. An allocation request with C set 
to four and P set to one results in two groups of four pixel values. The four base pixel values are 
assigned the four normal colors, and the four alternate pixel values are all assigned the fifth color. 
Overlay graphics can then be drawn by restricting output (see the next section) to the single bit plane 
specified in the mask returned by the color allocation. Turning bits in this plane on (to ones) changes the 
image to the fifth color, and turning them off reverts the image to its original color. 


6. Graphics and Text 

Graphics operations are often the most complex part of any window system, simply because so many 
different effects and variations are required to satisfy a wide range of applications. In this section we 
sketch the operations provided in X, so that the basic level of graphics support can be understood. The 
operations are essentially a subset of the Digital Workstation Graphics Architecture; the VS100 
display [11] implements this architecture for 1-bit pixel values. The set of operations purposely was kept 
simple, in order to maximize portability. 

Graphics operations in X are expressed in terms of relatively high-level concepts, such as lines, 
rectangles, curves, and fonts. This is in contrast to systems in which the basic primitives are to read and 
write individual pixels. Basing applications on pixel-level primitives works well when display memory can 
be mapped into the application’s address space for direct manipulation. However, both display hardware 
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and operating systems exist for which such direct access is not possible, and emulating pixel-level 
manipulations in such an environment results in extremely poor performance. Expressing operations at a 
higher level avoids such device dependencies, and also avoids potential problems with network 
bandwidth. With high-level operations, a protocol request transmitted as a small number of bits over the 
network typically affects ten to one hundred times as many pixels on the screen. 

6.1. Images 

Two forms of off-screen images are supported in X: bitmaps and pixmaps. A bitmap is a single plane 
(bit) rectangle. A pixmap is an N-plane (pixel) rectangle, where N is the number of bits per pixel used by 
the particular display. A bitmap or pixmap can be created by transmitting all of the bits to the server; a 
pixmap can also be created by copying a rectangular region of a window. Bitmaps and pixmaps of 
arbitrary size can be created. Transmitting very large (or deep) images over a network connection can be 
quite slow; however, the ability to make use of shared memory in conjunction with the I PC mechanism 
would help enormously when the client and server are on the same machine. 

The primary use of bitmaps is as masks (clipping regions). Several graphics requests allow a bitmap to 
be used as a clipping region [35]. Bitmaps are also used to construct cursors, as described in Section 8. 
Pixmaps are used to store frequently drawn images, and as temporary backing-store for pop-up menus 
(as described in Section 8). However, the principal use of pixmaps is as tiles, that is, as patterns which 
are replicated in two dimensions to cover a region. Since there are often hardware restrictions as to what 
tile shapes can be replicated efficiently, guaranteed shapes are not defined by the X protocol. An 
application can query the server to determine what shapes are supported, although to date most 
applications simply assume 16 by 16 tiles are supported. A better semantics is to support arbitrary 
shapes, but allow applications to query as to which shapes are most efficient. 

The tiling origin used in X is almost always the origin of the destination window. That is, if enough tiles 
were laid out, one tile would have its upper left comer at the upper left corner of the window. In this way, 
the contents of the window are independent of the window’s position on the screen, and the window can 
be moved transparently to the application. 

Servers vary widely in the amount of off-screen memory provided. For example, some servers limit 
off-screen memory to that accessible directly to the graphics processor (typically one to three times the 
size of screen memory), and fonts and other resources are allocated from this same pool. Other servers 
utilize their entire virtual address space for off-screen memory. Since off-screen memory for images is 
finite, an explicit part of the X protocol is the possibility that bitmap or pixmap creation can fail. Depending 
on the intended use of the image, the application may or may not be able to cope with the failure. For 
example, if the image was being stored simply to speed up redisplay, the application can always transmit 
the image directly each time (see below). If the image was to be a temporary backing-store for a window, 
the application can fall back on normal exposure processing (as described in Section 7). Servers should 
be constructed in such a way as to virtually guarantee sufficient memory (e.g., by caching images) for 
creating at least small tiles and cursors, although this is not true in current implementations. 
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6.2. Graphics 

All graphics and text requests include a logic function and a plane-select mask (an integer with the 
same number of bits as a pixel value) to modify the operation. All sixteen logic functions are provided. 
Given a source and destination pixel, the function is computed bitwise on corresponding bits of the pixels, 
but only on bits specified in the plane-select mask. Thus the result pixel is computed as 
((source FUNC destination) AND mask) OR (destination AND (NOT mask)) 

The most common operation is simply replacing the destination with the source in all planes. 

The simplest graphics request takes a single source pixel value and combines it with every pixel in a 
rectangular region of a window. Typically this is used to fill a region with a color, but by varying the logic 
function or masks, other effects can be achieved. A second request takes a tile, effectively constructs a 
tiled rectangular source with it, and then combines the source with a rectangular region of a window. 

An arbitrary image can be displayed directly, without first being stored off-screen. For monochrome 
images, the full contents of a bitmap are transmitted, along with a pair of pixel values; the image is 
displayed in a region of a window with those two colors. For color images, the full contents of a pixmap 
can be transmitted and displayed. In order to avoid inordinate buffer space in the server, very large 
images must be broken into sections on the client side and displayed in separate requests. 

The CopyArea request allows one region of a window to be moved to (or combined with) another 
region of the same window. This is the usual bitblt, or "bit block transfer" operation. The source and 
destination are given as rectangular regions of the window; the two regions have the same dimensions. 
The operation is such that overlap of the source and destination does not affect the result. 

X provides a complex primitive for line drawing. It provides for arbitrary combinations of straight and 
curved segments, defining both open and closed shapes. Lines can be solid, by drawing with a single 
source pixel value, dashed, by alternately drawing with a single source pixel value and not drawing, and 
patterned, by alternately drawing with two source pixel values. Lines are drawn with a rectangular brush. 
Clients can query the server to determine what brush shapes are supported; a better semantics would be 
to support arbitrary shapes, but allow applications to query as to which shapes are most efficient. 

A final request allows an arbitrary closed shape (such as could be specified in the line drawing request) 
to be filled with either a single source pixel value or a tile. For self-intersecting shapes, the even-odd rule 
is used: a point is inside the shape if an infinite ray with the point as origin crosses the path an odd 
number of times. 

6.3. Text 

For high-performance text, X provides direct support for bitmap fonts. A font consists of up to 256 
bitmaps; each bitmap in a font has the same height but can vary in width. To allow server-specific font 
representations, clients "create" fonts by specifying a name rather than by downloading bitmap images 
into the server. An application can use an arbitrary number of fonts, but (as with all resources) font 
allocation can fail for lack of memory. A reasonably implemented server should support an essentially 
unbounded number of fonts (e.g., by caching), but some existing server implementations are deficient in 
this respect. Unlike Andrew [7], no heuristics are applied by the server when resolving a name to a font; 
specific communities or applications may demand a variety of heuristics, and as such they belong outside 
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the base window system. Also unlike Andrew, the X server is not free to dynamically substitute one font 
for another; we do not believe such behavior is necessary or appropriate. 

A string of text can be displayed using a font either as a mask or as a source. Using a font as a mask, 
the foreground (the one bits in the bitmap) of each character is drawn with a single source pixel value. 
Using a font as a source, the entire image of each character is drawn, using a pair of pixel values. 
Source font output is provided specifically for applications using fixed-width fonts in emulating traditional 
terminals. 

To support "cut and paste" operations between applications, the server provides a number of buffers 
into which a client can read and write an arbitrary string of bytes. (This mechanism was adopted from 
Andrew.) Although these buffers are used principally for text strings, the server imposes no interpretation 
on the data, so cooperating applications can use the buffers to exchange such things as resource 
identifiers and images. 

7. Exposures 

Given that output to obscured windows is possible, the issue of exposure must be addressed. When 
all (or a piece) of an obscured window again becomes visible (for example, as the result of the window 
being raised), is the client or the server responsible for restoring the contents of the window? In X, it is 
the responsibility of the client. When a region of a window becomes exposed, the server sends an 
asynchronous event to the client, specifying the window and the region that has been exposed; the rest is 
up to the application. A trivial application might simply redraw the entire window; a more sophisticated 
application would only redraw the exposed region. 

Why is the client responsible? Because X imposes no structure on, or relationships between, graphics 
operations from a client, there are only two basic mechanisms by which the server might restore window 
contents: by maintaining display lists, and by maintaining off-screen images. In the first approach, the 
server essentially retains a list of all output requests performed on the window. When a region of the 
window becomes exposed, the server either re-executes all requests to the entire window, or only re- 
executes requests that affect the region while clipping the output to that region. In the alternative 
approach, when a window becomes obscured the server saves the obscured region (or perhaps the 
entire window) in off-screen memory. All subsequent output requests are executed not only to the visible 
regions of the window, but to the off-screen image as well. When an obscured region becomes visible 
again, the off-screen copy is simply restored. 

We believe neither server-based approach is acceptable. With display lists, the server is unlikely to 
have any reasonable notion of when later output requests nullify earlier ones. Either the display list 
becomes unmanageably long, and a refresh that should appear nearly instantaneous instead appears as 
a slow-motion replay, or the server spends a significant length of time pruning the display list, and normal- 
case performance is considerably reduced. One problem with the off-screen image approach is (virtual) 
memory consumption: on a 1024 by 1024 8-plane display, just one full-screen image requires one 
megabyte of storage, and multiple overlapping windows could easily require many times that amount. 
Another problem is that the cost of the implementation can be prohibitive. Consider, for example, the 
QDSS display [34], which has a graphics co-processor. In the QDSS, display memory is inaccessible to 
the host processor. In addition, the co-processor cannot perform operations in host memory, and has 
relatively little off-screen memory of its own. The only viable way to maintain off-screen images for 
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displays like the QDSS may be to emulate the co-processor in software. It can easily take tens of 
thousands of lines of code to emulate a co-processor, and such emulation may execute orders of 
magnitude slower than the co-processor. 

Our belief is that many applications can take advantage of their own information structures to facilitate 
rapid redisplay, without the expense of maintaining a distinct display structure or backing-store in the 
client or the server, and often with even better performance. (Sapphire [17] permits client refresh for this 
reason.) For example, a text editor can redisplay directly from the source, and a VLSI editor can 
redisplay directly from the layout and component definitions. Many applications will be built on top of 
high-level graphics libraries that automatically maintain the data structures necessary to implement rapid 
redisplay. For example, the structured display file mechanism in VGTS could be supported in a client 
library. Of course, pushing the responsibility back on the application may not simplify matters, particularly 
when retrofitting old systems to a new environment. For example, the current GKS design does not 
provide adequate hooks for automatic, system-generated refresh of application windows, nor does it 
provide an adequate mechanism for forcing refresh back on the application. 

Relying on client-controlled refresh also derives from window management philosophy. Our belief is 
that applications cannot be written with fixed top-level window sizes built in. Rather, they must function 
correctly with almost any size, and continue to function correctly as windows are dynamically resized. 
This is necessary if applications are to be usable on a variety of displays under a variety of window 
management policies. (Of course, an application may need a minimum size to function reasonably, and 
may prefer the width or height to be a multiple of some number; X allows the client to attach a resize hint 
to each window to inform window managers of this.) Our belief is that most applications, for one reason 
or another, will already have code for performing a complete redisplay of the window, and that it is usually 
straightforward to modify this code to deal with partial exposures. Similar arguments were used in the 
design of both Andrew and Mex, and experience has confirmed their decision [7, 23]. 

This is not to argue that the server should never maintain window contents, only that it should not be 
required to maintain contents. For complex imaging and graphics applications, efficient maintenance by 
the server may be critical for acceptable performance of window management functions. There is nothing 
inherent in the X protocol that precludes the server from maintaining window contents and not generating 
exposure events. In the next version of X, windows will have several attributes to advise the server as to 
when and how contents should be maintained. 

In X, clients are never informed of what regions are obscured, only of what regions have become 
visible. Thus, clients have insufficient information to try and optimize output by only drawing to visible 
regions. However, we feel this is justified on two grounds. First, realistically, users seldom stack 
windows such that the active ones are obscured, so there is little point in complicating applications to 
optimize this case. More importantly, allowing applications to restrict output to only visible regions would 
conflict with the desire to have the server maintain obscured regions automatically when possible. 

An interesting complication with the CopyArea request (described in Section 6) arises, having decided 
on client refresh. If part of the source region of the CopyArea is obscured, then not all of the destination 
region can be updated properly, and the client must be notified (with an exposure event) so that it can 
correct the problem. Since output requests are asynchronous, care must be taken by the application to 
handle exposure events when using CopyArea. In particular, if a region is exposed and an event sent by 



the server, a subsequent CopyArea may move all or part of the region before the event is actually 
received by the application. Several simple algorithms have been designed to deal with this situation, but 
we will not present them here. 

Client refresh raises a visual problem in a network environment. When a region of a window becomes 
exposed, what contents should the server initially place in that window? In a local, tightly-coupled 
environment, it might be perfectly reasonable to leave the contents unaltered, because the client can 
almost instantaneously begin to refresh the region. In a network environment however (and even in a 
local system where processes can get "swapped out" and take considerable time to swap back in), 
inevitable delays can lead to visually confusing results. For example, the user may move a window, and 
see two images of the window on the screen for a significant length of time, or resize a window and see 
no immediate change in the appearance of the screen. 

To avoid such anomalies in X, clients must define a background for every window. The background 
can be a single color, or it can be a tiling pattern. Whenever a region of a window is exposed, the server 
immediately paints the region with the background. Users therefore see window shapes immediately, 
even if the "contents" are slow to arrive. Of course, many application windows have some notion of a 
background anyway, so having the server initialize with a background seldom results in extraneous 
redisplay. In fact, many non-leaf windows typically contain nothing but a background, and having the 
server paint that background frees the applications from performing any redisplay at all to those windows. 

Although we believe client-generated refresh is acceptable most of the time, it does not always perform 
well with momentary pop-up menus, where speed is at a premium. To avoid potentially expensive refresh 
when a menu is removed from the screen, a client can explicitly copy the region to be covered by the 
menu into off-screen memory (within the server) before mapping the menu window. A special unmap 
request is used to remove the menu: it unmaps the window without affecting the contents of the screen 
or generating exposure events. The original contents are then copied back onto the screen. In addition, 
the client usually grabs the server for the entire sequence, using a request which freezes all other clients 
until a corresponding ungrab request is issued (or the grabbing client terminates). Without this, 
concurrent output from other clients to regions obscured by the menu would be lost. Although freezing 
other clients is in general a poor idea, it seems acceptable for momentary menus. 


8. Input 

We now turn to a discussion of input events, but first we briefly describe the support for mouse cursors. 
Clients can define arbitrary shapes for use as mouse cursors. A cursor is defined by a source bitmap, a 
pair of pixel values with which to display the bitmap, a mask bitmap which defines the precise shape of 
the image, and a coordinate within the source bitmap which defines the "center" or "hot spot” of the 
cursor. Cursors of arbitrary size can be constructed, although only a portion of the cursor may be 
displayed on some hardware. Clients can query the server to determine what cursor sizes are supported, 
but existing applications typically just assume a 16 by 16 image can always be displayed. Cursors also 
can be constructed from character images in fonts; this provides a simple form of named indirection, 
allowing custom tailoring to each display without having to modify the applications. 

A window is said to contain the mouse if the hot spot of the cursor is within a visible portion of the 
window or one of its subwindows. The mouse is said to be in a window if the window contains the mouse 
but no subwindow contains the mouse. Every window can have a mouse cursor defined for it. The 



server automatically displays the cursor of whatever window the mouse is currently in; if the window has 
no cursor defined, the server displays the cursor of the closest ancestor with a cursor defined. 

Input is associated with windows. Input to a given window is controlled by a single client, which need 
not be the client that created the window. Events are classified into various types, and the controlling 
client selects which types are of interest to it. Only events matching in type with this selection are sent to 
the client. When an input event is generated for a window and the controlling client has not selected that 
type, the server propagates the event to the closest ancestor window for which some client has selected 
the type, and sends the event to that client instead. Every event includes the window that had the event 
type selected; this window is called the event window. If the event has been propagated, the event also 
includes the next window down in the hierarchy between the event window and the original window on 
which the event was generated. 

8.1 . The Keyboard 

For the keyboard, a client can selectively receive events on the press or release of a key. Keyboard 
events are not reported in terms of ASCII character codes; instead, each key is assigned a unique code, 
and client software must translate these codes into the appropriate characters. The mapping from 
keycaps to keycodes is intended to be "universal" and predefined; a given keycap has the same keycode 
on all keyboards. Applications generally have been written to read a "keymap file" from the user’s home 
directory, so that users can remap the keyboard as they see fit. 

The use of coded keys is secondary to the ability to detect both up and down transitions on the 
keyboard. For example, a common trick in window systems is for mouse button operations to be affected 
by keyboard modifiers such as the Shift, Control, and Meta keys. A useful feature of the Genera [ 31 ] 
system is the use of a "mouse documentation line”, which changes dynamically as modifiers are pressed 
and released, indicating the function of the mouse buttons. A base window system must provide this 
capability. Transitions are not only useful on modifiers; various applications for systems other than X 
have been designed to use "chords" (groups of keys pressed simultaneously), and again the window 
system should support them. 

The keyboard is always attached to some window (typically the root window or a top-level window); we 
call this window the focus window. A request can be used (usually by the input manager) to attach the 
keyboard to any window. The window that receives keyboard input depends on both the mouse position 
and the focus window. If the mouse is in some descendant of the focus window, that descendant 
receives the input. If the mouse is not in a descendant of the focus window, then the focus window 
receives the input, even if the mouse is outside the focus window. For applications that wish to have the 
mouse state modify the effect of keyboard input, a keyboard event contains the mouse coordinates, both 
relative to the event window and global to the screen, as well as the state of the mouse buttons. 

To provide a reasonable user interface, keyboard events also contain the state of the most common 
modifier keys: Shift, ShiftLock, Control, and Meta. Without this information, anomalous behavior can 
result. If the user switches windows while modifier keys are down, the new client must somehow 
determine which modifiers are down. Placing the modifier state in the keyboard events solves such 
problems, and also has another benefit: most clients do not have to maintain their own shadow of the 
modifier state, and so often can completely ignore key release events. However, there is a conflict 
between this server-maintained state and client-maintained keyboard mappings. In particular, clients 
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cannot use non-standard keys as modifiers, or use chords without the possibility of anomalies such as 
described above. We believe the correct solution (not yet supported in X) is for the server to maintain a 
bit mask reflecting the full state of the keyboard, and to allow clients to read this mask. An application 
using chords or non-standard modifiers would request the server to send this mask automatically 
whenever the mouse entered the application's window. 

8.2. The Mouse 

The X protocol is (somewhat arbitrarily) designed for mice with up to three buttons. An application can 
selectively receive events on the press or release of each button. Each event contains the current mouse 
coordinates (both local to the window and global to the screen), the current state of all buttons and 
modifier keys, and a timestamp which can be used, for example, to decide when a succession of clicks 
constitutes a double or triple click. An application can also choose to receive mouse motion events, either 
whenever the mouse is in the window, or only when particular buttons have also been pressed. The 
application cannot control the granularity of the reporting, nor is any minimum granularity guaranteed. In 
fact, typical server implementations make an effort to compact motion events, to minimize system 
overhead and wired memory in device drivers. As such, X may not serve adequately for fine-grained 
tracking, such as in fast moving free-hand drawing applications. 

Even with motion compaction, servers can generate considerable numbers of motion events. If an 
application attempts to respond in real time to every event, it can easily get far behind relative to the 
actual position of the mouse. Instead, many applications simply treat motion events as hints. When a 
motion event is received, the event is simply discarded, and the client then explicitly queries the server for 
the current mouse position. In waiting for the reply, more motion events may be received; these are also 
discarded. The client then reacts based on the queried mouse position. The advantage of this scheme 
over continuously polling the mouse position is that no CPU time is consumed while the mouse is 
stationary. 

Clients can also receive an event each time the mouse enters or leaves a window. This can be 
particularly useful in implementing menus. For example, each menu item can be placed in a separate 
subwindow of the overall menu window. When the mouse enters a subwindow, the item is highlighted in 
some fashion (e.g., by inverting the video sense), and when the mouse leaves the window the item is 
restored to normal. Implementing a menu in this manner requires considerably less CPU overhead than 
continuous polling of the mouse, and also less overhead than using motion events, since most motion 
events would be within windows and thus uninteresting. 

Due to the nature of overlapping windows, and because continuous tracking by the server is not 
guaranteed, the mouse may appear to move instantaneously between any pair of windows on the screen. 
Certainly the window the mouse was in should be notified of the mouse leaving, and the window the 
mouse is now in should be notified of the mouse entering. However, all of the windows "in between" in 
the hierarchy may also be interested in the transition. This is useful in simplifying the structure of some 
applications, and is necessary in implementing certain kinds of window managers and input managers. 
Thus, when the mouse moves from window A to window B, with window W as their closest (least) 
common ancestor, all ancestors of A below W also receive leave events, and all ancestors of B below W 
receive enter events. 


L 


Except for mouse motion events, it might be argued that events are infrequent enough that the server 
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should always send all events to the client, and eliminate the complexity of selecting events. However, 
some applications are written with interrupt-driven input; events are received asynchronously, and cause 
the current computation to be suspended so that the input can be processed. For example, a text editor 
might use interrupt-driven input, with the normal computation being redisplay of the window. The receipt 
of extraneous input events (for example, key release events) can cause noticeable "hiccups" in such 
redisplay. 


9. Input and Window Management 

There are two basic modes of keyboard management: real-estate and listener. In real-estate mode, 
the keyboard "follows" the mouse; keyboard input is directed to whatever window the mouse is in. In 
listener mode, keyboard input is directed to a specific window, independent of the mouse position. Some 
systems provide only real-estate mode [1,28], some only listener mode [8, 17, 19, 23, 30, 31], and 
Andrew [7] provides both, although the mode cannot be changed during a session. Both modes are 
supported in X, and the mode can be changed dynamically. Real-estate mode is the default behavior, 
with the root window as the focus window, as described in the previous section. An input manager can 
also make some other (typically top-level) window the focus window, yielding listener mode. Note 
however, that in listener mode in X, the client controlling the focus window can still get real-estate 
behavior for subwindows, if desired; this capability has proven useful in several applications. 

The primary function of a window manager is reconfiguration: restacking, resizing, and repositioning 
top-level windows. The configuration of nested windows is assumed to be application-specific, and under 
control of the applications. There are two broad categories of window managers: manual and automatic. 
A manual window manager is "passive", and simply provides an interface to allow the user to manipulate 
the desktop; windows can be resized and reorganized at will. The initial size and position of a window 
typically (but not always) is under user or application control. Automatic window managers are "active", 
and operate for the most part without human interaction; size and position at window creation, and 
reconfiguration at window destruction, are chosen by the system. Automatic managers typically tile the 
screen with windows, such that no two windows overlap, automatically adjusting the layout as windows 
are created and destroyed. Andrew [7], Star [24], and Cedar [32] provide automatic management, plus 
limited manual reconfiguration capability. 

Existing window managers for X are manual. Automatic management that is transparent to 
applications cannot be accomplished reasonably in X; future support for automatic management is 
discussed in Section 10. In the current X design, clients are responsible for initially sizing and placing 
their top-level windows, not window managers. In this way, applications continue to work when no 
window manager is present. Typically, the user either specifies geometry information in the application 
command line, or uses the mouse to sweep out a rectangle on the screen. (For the latter, the application 
grabs the mouse, as described below.) 


9.1. Mouse-Driven Management 

Existing managers are primarily mouse-driven, and are based on the ability to "steal" events. 
Specifically, a manager (or any other client) can grab a mouse button in combination with a set of modifier 
keys, with the following effect. Whenever the modifier keys are down and the button is pressed, the event 
is reported to the grabbing client, regardless of what window the mouse is in. All mouse-related events 
continue to be sent to that client until the button is released. As part of the grab, the client also specifies 



a mouse cursor to be used for the duration of the grab, and a window to be used as the event window. A 
manager specifies the root window as the event window when grabbing buttons; with the event 
propagation semantics described in Section 8, the grabbed events contain not only the global mouse 
coordinates, but also the top-level application window (if any) containing the mouse. This is sufficient 
information to manipulate top-level windows. 

Using this button-grab mechanism, several different management interfaces have been built, including 
a "programmable" interface [5] allowing the user to assign individual commands or user-defined menus of 
commands to any number of button/modifier combinations. For example, a button click (press and 
release without intervening motion) might be interpreted as a command to raise or lower a window, or to 
attach the keyboard; a press/motion/release sequence might be interpreted as a command to move a 
window to a new position; or a button press might cause a menu to pop up, with the selection indicated by 
the mouse position at the release of the button. By allowing both specific commands and menus to be 
bound to buttons, a range of interfaces can be constructed to satisfy both "expert" and "novice" users. 

Another form of manager simply displays a static menu bar along the top of the screen, with items for 
such operations as moving a window and attaching the keyboard. The menu is used in combination with 
a mouse-grab primitive, with which a client can unilaterally grab the mouse and then later explicitly 
release it; during such a mouse-grab, events are redirected to the grabbing client, just as for button-grabs. 
When the user clicks on a menu bar item with any button, the manager unilaterally grabs the mouse. The 
user then uses the mouse to execute the specific command. For example, having clicked on the "move" 
item, the user indicates the window to move by placing the mouse in the window and pressing a button, 
then indicates the new position by moving the mouse and releasing the button. The manager then 
releases the mouse. 

9.2. Icons 

One important "resizing" operation performed by a window manager is transforming a window into a 
small icon and back again. In X, icons are merely windows. Transforming a window into an icon simply 
involves unmapping the window and mapping its associated icon. The association between a window 
and its icon is maintained in the server, rather than the window manager, and either the application or the 
manager can provide the icon. In this way, the manager can provide a default icon form for most clients, 
but clients can provide their own if desired, possibly with dynamic rather than static contents. The client is 
still insulated from management policy, even if it provides the icon: the manager is responsible for 
positioning, mapping, and unmapping the icon, and the ciient is responsible only for displaying the 
contents. 

The icon state is maintained in the server not only to allow clients to provide icons, but to avoid the loss 
of state if the window manager should terminate abnormally. When a window manager terminates, any 
windows it has created are destroyed, including icon windows. With knowledge of icons, the server can 
detect when an icon is destroyed, and automatically remap the associated client window. Without this, 
abnormal termination of the window manager would result in "lost" windows. 



9.3. Race Conditions 

There are many race conditions that must be dealt with in input and window management, due to the 
asynchronous nature of event handling. For example, if a manager attempts to grab the mouse in 
response to a press of a button, the mouse-grab request might not reach the server until after the button 
is released, and intervening mouse events would be missed. Or, if the user clicks on a window to attach 
the keyboard there, and then immediately begins typing, the first few keystrokes might occur before the 
manager actually responds to the click and the server actually moves the keyboard focus. A final 
example is a simple interface in which clicking on a window lowers it. Given a stack of three windows, the 
user might rapidly click twice in the same spot, expecting the top two windows to be lowered. Unless the 
first click is sent to the manager and the resulting request to lower is processed by the server before the 
second click takes place, the event window for the second click will be the same as for the first click, and 
the manager will lower the first window twice. 

A work-around for the last example, used by existing managers, is to ignore the event window reported 
in most events. Instead, the global mouse coordinates reported in the event are used in a follow-up query 
request to determine which top-level window now contains that coordinate. However, not all race 
conditions have acceptable solutions within the current X design. For a general solution, it must be 
possible for the manager to synchronize operations explicitly with event processing in the server. For 
example, a manager might specify that, at the press of a button, event processing in the server should 
cease until an explicit acknowledgment is received from the manager. 

10. Future 

Based on critiques from numerous universities and commercial firms, a fairly extensive evaluation and 
redesign of the X protocol has been underway since May 1986. Our desire is to define a "core" protocol 
that can serve as a standard for window system construction over the next several years. We expect to 
present the rationale for this new design in the very near future, once it has been validated by at least a 
preliminary implementation. In this section, we highlight the major protocol changes. 

10.1. Resource Allocation 

Since the server is responsible for assigning identifiers to resources, each resource allocation currently 
requires a round-trip time to perform. For applications that allocate many resources, this causes a 
considerable start-up delay. For example, a multi-pane menu might consist of dozens of windows, 
numerous fonts, and several different mouse cursors, leading to a delay of one second or longer. 

In retrospect, this is the most significant defect in the design of X. To get around these delays, 
programming interfaces have been augmented to provide "batch mode" operations. If several resources 
must be created, but there are no inter-dependencies among the allocation requests, all of the requests 
are sent in a batch, and then all of the replies are received. This effectively reduces the delay to a single 
round-trip time. 

A better solution to this problem is to make clients generate the identifiers. When the client establishes 
a connection to the server, it is given a specific subrange from which it can allocate. This change will 
significantly improve start-up times without affecting applications, as identifiers can be generated inside 
low-level libraries without changing programming interfaces. 
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10.2. Transparent Windows 

One use of transparent windows is as clipping regions. However, they are unsatisfactory for this 
purpose because every coordinate in a graphics request must be translated by the client from the "real" 
window’s origin to the transparent window’s origin. A better approach to clipping regions is to allow 
clients to create clipping regions and attach them to all graphics requests. As noted in Section 6, X 
currently allows a clipping region in the form of a bitmap to be attached to a few graphics requests. 
Allowing a clipping region, specified either as a bitmap or a list of rectangles, to be attached to all 
graphics requests provides a more uniform mechanism. 

The major use of transparent windows to date is actually as inexpensive opaque windows. In the 
current server implementation, transparent windows can be created and transformed significantly faster 
than opaque windows. Because of this, transparent windows are often used when opaque windows 
would otherwise be adequate. We believe a new implementation of the server will improve the 
performance of opaque windows to the point that this will no longer be necessary. 

With explicit clipping regions added for graphics, and the performance advantages of transparent 
windows reduced, the only remaining use of transparent windows is for input (and cursor) control. 
Various applications want relatively fine-grained input control, and such control must not affect graphics 
output. Close control of cursor images and mouse motion events seems particularly important. However, 
the vast majority of the time control naturally is associated with normal window boundaries, so it would be 
unwise to divorce input control completely from windows. As such, the new protocol provides "input-only” 
windows, which act like normal windows for the purposes of input and cursor control, but which cannot be 
used as a source or destination in graphics requests, and which are completely invisible as far as output 
is concerned. 

10.3. Color 

X originally was not designed to deal with direct-color displays. Direct-color displays typically have 
between 12 and 36 bits per pixel; the pixel value consists of three subfields, which are used as indexes 
into three independent color maps: one for red intensities, one for green, and one for blue. Some direct- 
color displays also have a fourth subfield, sometimes referred to as "z-channel” information, used to 
control attributes such as blending or chroma keying. We now understand how to incorporate direct-color 
displays without z-channel information into X, in such a way that the differences between direct-color and 
pseudo-color color maps need not be apparent to the application, yet still allowing all of the usual color 
map tricks to played. 


At present there is only one color map for all applications, and color applications fail when this map 
gets full. Although dozens of applications typically can be run under X within a single 8-bit pseudo-color 
map, a single map is clearly unacceptable when dealing with small color maps, or with multiple 
applications (e.g., CAD tools) that need large portions of the color map. The solution is to support 
multiple virtual color maps, still permitting applications to coexist within any map, but allowing the 
possibility that not all applications show true color simultaneously. This also matches next-generation 
displays, which actually support multiple color maps in hardware [37], 
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10.4. Graphics 

Perhaps the biggest mistake in the graphics area was failing to support fonts with kerning (side 
bearings). For example, a relatively complete emulation of the Andrew programming interface was built 
for X, but Andrew applications depend heavily on kerned fonts. There are other deficiencies that will be 
corrected. For example, large glyph-sets (e.g., Japanese) will be supported, as well as stippling (using a 
clip mask constructed by tiling a region with a bitmap). The notions of line width, join style, and end style 
found in PostScript [22] are usually preferred to brush shapes for line drawing, and will be supported. 

In an attempt to support a wide range of devices, the exact path followed for lines and filled shapes 
was originally left undefined in X (the class of curve was not even specified). Different devices use 
slightly different algorithms to draw straight lines, and it seemed better to have high performance with 
minor variation than to have uniformity with poor performance. Relatively few devices support curve 
drawing in hardware, but some support it in firmware, and again performance seemed more important 
than accuracy. In retrospect, however, allowing such device dependent behavior was a poor decision. 
The vast majority of applications draw lines aligned on an axis, and speed and precision are not an issue. 
The applications that do require complex shapes also require predictable results, so precise specifications 
are important. 

A notable feature missing in X is the ability to perform graphics operations off screen. The reasons for 
this are essentially the same as those presented when discussing exposures in Section 7. In particular, 
not all graphics co-processors can operate on host memory, and emulating such processors can be 
expensive. However, application builders have demanded this capability, and the demand appears to be 
sufficient leverage to convince server implementors to provide the capability. Off-screen graphics will be 
possible in the new protocol, although the amount of off-screen memory and its performance 
characteristics may vary widely. In addition, the protocol is being extended to allow the manipulation of 
both images and windows of varying depths. For example, a server might support depths of 1, 4, 8, 12, 
and 24 bits. This allows imaging applications to transmit data more compactly, allows for more efficient 
memory utilization in the server, and provides a match with next-generation display hardware. 

A common debate in graphics systems is whether and where to have state. Should parameters such 
as logic function, plane mask, source pixel value or tile, tiling origin, font, line width and style, and clipping 
region be explicit in every request or collected into a state object? The current X protocol is stateless, for 
the following reasons: both state and stateless programming interfaces can be built easily on top of the 
protocol; the currently supported graphics requests have just few enough parameters that they can be 
represented compactly; and the initial set of displays we were interested in (and the implementations we 
had in mind for them) would not benefit from the addition of state. However, we now believe that a 
state-based protocol is generally superior, as it handles complex graphics gracefully and allows 
significantly faster implementations on some displays. 

10.5. Management 

An obvious interface style presently not supported in X is the ability to use the keyboard for 
management commands. To allow this, a key-grab mechanism, akin to the button-grab mechanism 
described in Section 9, will be provided. To allow such styles as using the first button click in a window to 
attach the keyboard, both button-grabs and key-grabs have been extended to apply to specific sub- 
hierarchies, rather than always to the entire screen. To handle the kinds of race conditions described in 



Section 9, a general event synchronization mechanism has been incorporated into the grab mechanisms. 

To support automatic window management, a manager must be able to intercept certain management 
requests from clients (such as mapping or moving a window) before they are executed by the server, and 
to be notified about others (such as unmapping a window) after they are executed. In addition, some 
managers want to provide uniform title bars and border decorations automatically. To allow this, it is 
useful to be able to "splice" hierarchies: to move a window from one parent to another. To allow input 
managers and window managers to be implemented as separate applications, the ability for multiple 
clients to select events on the same window is being added. For example, both a window manager and 
an input manager might be interested in the unmapping or destruction of a window. 

10.6. Extensibility 

The information that input and window managers might desire from applications is quite varied, and it 
would be a mistake to try and define a fixed set. Similarly, the information paths between applications 
(e.g., in support of "cut and paste") need to be flexible. To this end, we are adding a Lisp-ish property 
list [26] mechanism to windows, and the event mechanism is being augmented to provide a simple form 
of inter-client communication. 

The new X protocol explicitly continues to avoid certain areas, such as 3-D graphics and anti-aliasing. 
However, a general mechanism has been designed to allow extension libraries to be included in a server. 
The intention is that all servers implement the "core" protocol, but each server can provide arbitrary 
extensions. If an extension becomes widely accepted by the X community, it can be adopted as part of 
the core. Each extension library is assigned a global name, and an application can query the server at 
run-time to determine if a particular extension is present. Request opcodes and event types are allocated 
dynamically, so that applications need not be modified to execute in each new environment. 

11. Summary 

The X Window System provides high-performance, high-level, device-independent graphics. A 
hierarchy of resizable, overlapping windows allows a wide variety of application and user interfaces to be 
built easily. Network-transparent access to the display provides an important degree of functional 
separation, without significantly affecting performance, that is crucial to building applications for a 
distributed environment. To a reasonable extent, desktop management can be custom tailored to 
individual environments, without modifying the base system and typically without affecting applications. 

To date, the X design and implementation effort has focused on the base window system, as described 
in this paper, and in essential applications and programming interfaces. The design of the network 
protocol, the design and implementation of device-independent layer of server, and the implementation of 
several applications and a prototype window manager, were carried out by the first author. The design 
and implementation of the C programming interface, the implementation of major portions of several 
applications, and the coordination of efforts within Project Athena and Digital, were carried out by the 
second author. In addition, many other persons from Project Athena, the Laboratory for Computer 
Science, and institutions outside MIT have contributed software. 

Necessary applications such as window managers and VT100 and Tektronics 4014 terminal emulators 
have been created, and numerous existing applications, such as text editors and VLSI layout systems, 
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have been ported to the X environment. Although several different menu packages have been 
implemented, we are only now beginning to see a rich library of tools (scroll bars, frames, panels, more 
menus, etc.) to facilitate the rapid construction of high-quality user interfaces. Tool building is taking 
place at many sites, and several universities are now attempting to unify window systems work with X as 
a base, so that such tools can be shared. 

The use of X has grown far beyond anything we had imagined. Digital has incorporated X into a 
commercial product, and other manufacturers are following suit. With the appearance of such products, 
and the release of complete X sources on the Berkeley 4.3 Unix distribution tapes, it is no longer feasible 
to track all X use and development. Existing applications written in C are known to have been ported to 
seven machine architectures of more than twelve manufacturers, and the C server to six machine 
architectures and more than sixteen display architectures. In most cases the code is running under Unix, 
but other operating systems are also involved. In addition, relatively complete server implementations 
exist in two Lisp dialects. Apart from designing the system to be portable, a large part of this success is 
due to MIT’s decision to distribute X sources without any licensing restrictions, and the willingness of 
people in both educational and commercial institutions to contribute code without restrictions. 

Acknowledgments 

Our thanks go to the many people who have contributed to the success of X. Particular thanks go to 
those who have made significant contributions to the non-proprietary implementation: Paul Asente 
(Stanford University), Scott Bates (Brown University), Mike Braca (Brown), Dave Bundy (Brown), Dave 
Carver (Digital), Tony Della Fera (Digital), Mike Gancarz (Digital), James Gosling (Sun Microsystems), 
Doug Mink (Smithsonian Astrophysical Observatory), Bob McNamara (Digital), Ron Newman (MIT), Ram 
Rao (Digital), Dave Rosenthal (Sun), Dan Stone (Brown), Stephen Sutphen (University of Alberta), and 
Mark Vandevoorde (MIT). 

Special thanks go to Digital Equipment Corporation. A redesign of the protocol and a reimplementation 
of the server to deal with color and to increase performance was made possible with funding (in the form 
of hardware) from Digital. To their credit, all of the resulting device-independent code remained the 
property of MIT. 



References 


1. ??? Apollo,??? 

2. Asente, P. W Reference Manual. Stanford University, 1984. internal document. 

3. Balkovich, E., Lerman, S., and Parmelee, R. "Computing in Higher Education: The Athena 
Experience". Communications of the ACM 28, 1 1 (Nov. 1985). 

4. Cheriton, D. "The V Kernel: A Software Base for Distributed Systems". IEEE Software 1 , 2 (April 
1984). 

5. Gancarz, M. UWM: A User Interface for X Windows. Summer Conference Proceedings, Atlanta, 
USENIX Association, 1986. 

6. Gettys, J. Problems Implementing Window Systems in Unix. Winter Conference Proceedings, 
Denver, USENIX Association, 1986. 

7. Gosling, J. and Rosenthal, D. A Window-Manager for Bitmapped Displays and Unix. In Methodology 
of Window-Managers, F. R. A. Hopgood et al, Eds., Springer-Verlag, 1986. 

8. Hawley, M. J., and Leffler, S. J. Windows for Unix at Lucasfilm. Summer Conference Proceedings, 
Portland, USENIX Association, 1985. 

9. Information Processing: Graphical Kernel System (GKS) - Functional Description. DIS 7942, 
International Standards Organisation, 1982. 

10. Lantz, K.A. and Nowicki, W. I. "Structured Graphics for Distributed Systems". ACM Transactions on 
Graphics 3, 1 (Jan. 1984). 

11. Levy, H. "VAXstation: A General-Purpose Raster Graphics Architecture". ACM Transactions on 
Graphics 3, 1 (Jan. 1984). 

12. Lipkie, D. E., Evans, S. R., Newlin, J. K., and Weissman, R. L. "Star Grapics: An Object-Oriented 
Implementation". Computer Graphics 16, 3 (July 1982). 

13. Liskov, B. and Scheifler, R. "Guardians and Actions: Linquistic Support for Robust, Distributed 
Programs". ACM Transactions on Programming Languages and Systems 5, 3 (July 1983). 

14. ??? MassComp, Inc., ??? 

15. Moon, D. Chaosnet. Al Memo 628, MIT Artificial Intelligence Laboratory, June, 1981. 

16. Morris, J., et al. "Andrew: A Distributed Personal Computing Environment". Communications of the 
ACM 29, 3 (March 1986). 

17. Myers, B. Issues in Window Management Design and Implementation. In Methodology of 
Window-Managers, F. R. A. Hopgood et al, Eds., Springer-Verlag, 1986. 

18. Nowicki, W. Partitioning of Function in a Distributed Graphics System. Ph.D. Th., Stanford 
University, Stanford, CA, 1985. 

19. ??? ICL, ??? 

20. Pike, R. "The Blit: A Multiplexed Graphics Terminal". AT&T Bell Laboratories Technical Journal 63, 
8 (Oct. 1984). 

21. Postel, J. Transmission Control Protocol. RFC 793, USC/Information Sciences Institute, Sept., 

1981. 

22. Adobe Systems Inc.. PostScript Lanuage Reference Manual. Addison-Wesley, 1985. 



29 


23. Rhodes, R., Haeberli, P, and Hickman, K. Mex-A Window Manager for the IRIS. Summer 
Conference Proceedings, Portland, USENIX Association, 1985. 

24. Smith, D. C., et al. The Star User Interface: An Overview. Proceedings of the National Computer 
Conference, Houston, June, 1982. 

25. Stallman, R., Moon, D., and Weinreb, D. Lisp Machine Window System Manual. MIT Artificial 
Intelligence Laboratory, Aug., 1983. 

26. Steele, G. L.. Common Lisp: The Language. Digital Press, 1984. 

27. NeWS Preliminary Technical Overview. Sun Microsystems, Inc., 1986. 

28. Programmer’s Reference Manual for SunWindows. Sun Microsystems, Inc., 1985. 

29. Sweet, R. "Mesa Programming Environment". ACM SIGPLAN Notices 20,7 (July 1985). 

30. Sweetman, D. A Modular Window System for Unix. In Methodology of Window-Managers, 

F. R. A. Hopgood et al, Eds., Springer-Verlag, 1986. 

31. Programming the User Interface. Symbolics, Inc., 1986. 

32. Teitelman, W. The Cedar Programming Environment: A Midterm Report and Examination. CSL 
83-11, Xerox PARC, June, 1984. 

33. Trammel, R. D. A Capability Based Hierarchic Architecture for Unix Window Management. Summer 
Conference Proceedings, Portland, USENIX Association, 1985. 

34. VCB02 Video Subsystem Technical Manual. Educational Services, Digital Equipment Corporation, 
1986. Order Number AZ-GLGAB-MN. 

35. Warnock, J., and Wyatt, D. K. "A Device Independent Graphics Imaging Model for Use with Raster 
Devices". Computer Graphics 16, 3 (1982). 

36. Wecker, S. "DNA: The Digital Network Architecture". IEEE Transactions on Communications 
CIM-28, 4 (April 1980). 

37. Wilkes, A. J., et. al. "The Rainbow Workstation". The Computer Journal 27, 2 (May 1984). 



X.l 


Thu Apr 7 17:41:00 1988 


1 


.TH X 1 ”25 January 1986” ”X Version 10” 

.SH NAME 

X - A network transparent window system for Unix 

.SH DESCRIPTION 

.PP 

X is a network transparent windowing system developed at MIT which 
runs under Ultrix-32 Version 1.2 and 4.3BSD Unix. 

.PP 

X display servers run on computers with bitmap terminals. 

The server 

distributes user input to, and accepts output requests from various 
client programs located either on the same machine or elsewhere in the 
Internet . 

While 

a client normally runs on the same machine as the X server it is talking 
to, this need not be the case. 

.PP 


X supports overlapping windows, fully recursive subwindows, text and 
graphics operations within windows. 

For a full explanation of functions, see 
' 'Xlib - C Language X Interface'' document. 

.PP 

When you first log in on a display running X, you are 
using the \flxterm(l) \fP terminal emulator program. 

You need not learn anything extra to use a display running X as 
a terminal beyond moving the mouse cursor into the login window to 
log in normally. 

.PP 

X attempts to provide hooks for your favorite style of user interface; 
feel free to write your own if you don't like the style provided by 
existing window managers (see \f Ixwm(l) \fP, \f Ixnwm ( 1) \fP, or \fluwm(l) \fP) . 
These programs are used to manipulate existing top level windows, 
including moving, resizing, and iconifying existing windows. 

You should start your favorite window manager when you log in 
on a display running X. 

.PP 


Current client programs of X include a terminal emulator (\flxterm(l) \fp) , 

window managers ( \f Ixwm ( 1) \fP, \f Ixnwm (1) \fP and \f Iuwm (1) \fP) , 

bitmap editor (\f Ibitmap (1) \fP) , 

access control program (\f Ixhost (1) \fP) , 

user preference setting program (\f Ixset (1) \fP) , 

load monitor (\f Ixload (1) \fP) , clock (\f Ixclock (1) \fP) , 

impress previewer (\f Iximpv ( 1) \fP) , 

font displayer (\f Ixfd(l) \fP) , demos (\f Ixdemo (1) \fP) , 
and editors (e.g., \fIxted\fP) . 

On some systems, mail notification has been integrated (\f Ibiff (1) \fP) . 

.SH OPTIONS 


The following options can be given on the command 
started by \f Iinit (1) \fP using information stored 
(see \f Ittys (5) \fP, \fIX(8c)\fP for details): 

.ta \w'-0 color 'u 
. br 

\fB-a\fP # sets mouse acceleration (pixels) 

. br 

\fB-c\fP turns off key-click 

. br 


\fBc\fP # sets key-click volume (0-8) 

.br 

\fB-f\fp # sets feep(bell) volume (0-7) 

.br 


\fB-l\fp sets LockUpDownMode 

.br 


\fBl\fP sets LockToggleMode 
.br 


line to the 
in the file 


X server, usually 
\f I/etc/ttys\fP . 
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Abstract 

The X1 1 Window System defines a network protocol [4] for communication between a graphics 
server and an application. The X library [1] provides a procedural interface to the protocol, in 
which most calls are a thin veneer over the underlying protocol operations. 

The X toolkit [2] is an object-oriented construction kit built on top of the X library. The toolkit is 
used to write user interface components (“widgets”), to organize a set of widget instances into a 
complete user interface, and to link a user interface with the functionality provided by an 
application. 

This paper briefly describes the goals and structure of the X toolkit, shows a small application 
program that uses the toolkit, then shows two of the user interface components (widgets) used by 
the application. 1 


1. An Introduction to X 

The XII Window System defines a distributed, asynchronous protocol by which graphics 
servers and applications communicate. A graphics server can support multiple applications, and 
an application can use multiple servers. 

An application and a server can run on the same or on different machines. The X protocol 
assumes a server and an application are connected by a fast communication link like shared 
memory, Ethernet, or even a fast leased line. To minimize the effects of network latency, the X 
protocol is asynchronous: neither the server nor the application wait for acknowledgements. The 
X library occasionally feigns synchronicity for the convenience of the application; for example, the 
application can query the mouse position or ask for a new colormap entry by simply calling a 
procedure that waits for a reply from the server. 

The X library provides a procedural interface to the protocol. An application calls procedures in 
the X library to send window management and drawing commands to the server. The server 
sends event notifications to the application in response to user actions (moving the mouse, typing 
on the keyboard) and screen geometry changes (window exposure, size or position change, 
iconification). The X library queues events and packages them into a record structure; an 


'This paper submitted to usenix, Summer, 1988. Reprinted with the permission of the usenix Association. 
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application periodically polls the library for the next event. 

2. Why a Toolkit? 

The X library provides a powerful low-level interface, but this flexibility has a cost: even simple 
programs require many lines of code. The primary goal of the X toolkit is to reduce the effort 
needed to write an X application. While a program to write “Hello, world” based directly on the X 
library takes 40 executable statements [3], the equivalent toolkit program takes 5. The toolkit 
enables programmers to write a library of widgets like text labels, scroll bars, command buttons, 
and menus, and to assemble these widgets into a complete user interface with just a few lines of 
code. 

A secondary goal is to allow user customization of applications. Users can specify resources 
like colors, fonts, border widths, and sizes for any widget or for various sets of widgets with just a 
few lines of text. 

Finally, when an application synchronously queries the server it suffers the latency inherent in 
a round trip — hundreds of these queries quickly add up to several seconds. The toolkit 
extensively caches data on the application side to minimize this time. 

3. Intrinsics, Widgets, and Applications 

The intrinsics layer of the toolkit is a mostly policy-free foundation upon which widgets and 
applications are built. The intrinsics contain facilities to create, organize, and destroy widgets; to 
translate event sequences from the server into procedure calls that applications and widgets have 
registered; to read and write widget state; and to negotiate over screen real estate when a widget 
changes size or position. It also includes a few predefined widgets that deal with much of the 
boiler-plate data and code common to all widgets. 

A widget is a user interface component implemented using calls to the intrinsics and the X 
library. MIT’s Project Athena delivers a sample set of widgets with the toolkit intrinsics, which 
serve as examples of how to write commonly seen user interface components. The sample 
widgets can be replaced, customized, or used as is. Many applications use only existing widgets; 
a few supplement these with their own specialized widgets. 

An application uses the intrinsics to tie widgets together into a user interface and to bind this 
user interface to functions implemented by the application. Applications typically interact with X 
only through the toolkit. If an application programmer wants some specialized user interface 
component, he doesn’t embed it in his application, but instead writes a new widget that can be 
reused and shared with other programmers. 

$ 

4. How an Application Writer Sees the World 

An application consists of three conceptual parts: application functionality, user interface, and 
links between the two. This division makes it easier to modify the user interface without recoding 
the functionality. In actual code, the division between the interface and its linkage to the 
functionality is not clearly visible: the statements that link the user interface to the application's 
function are usually intertwined with the construction of that interface. 

The application functionality is a set of “callback” routines the toolkit calls in response to user 
actions. The xmh mail handler has routines to include new mail, read a message, reply to a 
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message, and so forth. When a user clicks on a command button in the user interface, the button 
calls one or more of these routines. 

The user interface is a tree of widget instances. Figure 4-1 shows the tree created by the 
example program below. The internal nodes are composite widgets, which don’t have any 
display or input semantics of their own, but are concerned only with managing the size and 
position of their children. The leaves of the tree are primitive widgets. A primitive widget cannot 
have children, and is concerned only with displaying portions of its state and responding to user 
input. 

An application links its functionality to its user interface by binding callbacks and data 
structures to widgets as it creates them. 

When the intrinsics invoke a callback routine, they pass the widget that caused the invocation, 
data registered with the toolkit when the application bound the callback, and widget-specific data. 
The application uses the application data if it needs to associate additional information with the 
widget. The format of the widget data is defined by the particular widget: A scroll-bar “thumb- 
changed” callback passes the address of a structure containing the new positioning information, 
while a command button callback supplies no extra information and so passes NULL. 





Figure 4-1 : The widget instance tree for the “Goodbye, world” program. 

5. A Simple Application: Goodbye, world. 

“Hello, world" has earned itself a beloved niche in the hearts of all C programmers. Times 
change, however, so to show the capabilities of the toolkit we present a more sophisticated 
example: the “Goodbye, world” program. It displays a window with a label and a command 
button; when the command button is clicked with the mouse the program prints a farewell 
message and terminates (Figure 5-1). 



Figure 5-1 : The output of the “Goodbye, world” program 
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Our example shows the main program and simple but complete versions of the label and 
command widgets it uses. We omit many details due to space limitations, and instead 
concentrate on the general flavor of toolkit programming. Refer to the intrinsics documentation 
[2] for further information. 

#include H lntrinsic.h M 
#include "Atoms. h H 
#include M Form.h N 
#include "Label. h" 

#include "Command.h" 

void Callback(widget, clientData, call Data) 

Widget widget; 

caddr_t clientData, callData; 

{ 

(void) printf("Goodbye, cruel world\n"); 
exit(O); 

} 

int main(argc, argv) 
unsigned int argc; 
char **argv; 

{ 

Widget toplevel, box, label, command; 

Arg arg[25]; 
unsigned int n; 

toplevel = Xtlnitializefgoodbye", "Goodbye", NULL, 0, &argc, argv); 

box = XtCreateManagedWidgetfbox", formWidgetClass, toplevel, (Arg *) NULL, 0); 


n = 0; 

XtSetArg(arg[n], XtNx, 10); n++; 

XtSetArg(arg[n], XtNy, 10); n++; 

XtSetArg(arg[n], XtNIabel, "Goodbye, world"); n++; 

label = XtCreateManagedWidget("labeJ", labelWidgetClass, box, arg, n); 

n = 0; 

XtSetArg(arg[n], XtNx, 10); n++; 

XtSetArg(arg[n], XtNy, 40); n++; 

XtSetArg(arg[n], XtNIabel, "Click and die"); n++; 


command = XtCreateManagedWidget("command", commandWidgetClass, box, arg, n); 

XtAddCallback(command, XtNcallback, Callback, NULL); 

XtRealizeWidget(toplevel); 

XtMainLoop(); 

} 

Figure 5-2: Goodbye.c: The “Goodbye, world” program. 

Figure 5-2 is the goodbye application. “Intrinsic.h” contains the definitions needed for 
applications to use the toolkit, “Atoms. h” contains predefined strings used as resource names, 
and “Form.h”, “Label. h”, and “Command.h” contain the definitions needed to use these widgets. 

The callback procedure Callback needs no additional information, so it ignores its parameters. 
It prints an exit message and terminates the program. 

The main program declares four widgets, toplevel, box, label, and command. Each application 
needs a special top level widget called a Shell that holds exactly one child and communicates 
with the outside world. Our application has two children, contained in the widget box. 

The application first calls the routine Xtlnitialize. Xtlnitialize establishes the name and class 
of the application based upon its first two parameters and uses these to read in user preferences 
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for application and widget resources. These preferences can be overridden by the command line 
arguments passed in as the last two parameters. Xtlnitialize establishes a connection with the 
server and returns a Shell widget for the application to use. 

Main creates the container widget, a Form widget named “box,” as a child of toplevel. 
XtCreateManagedWidget takes five parameters: the name of the widget instance, the class of 
the widget, a widget to use as the parent, a list of arguments to the widget, and the length of this 
list. “Box” has no extra arguments and so passes NULL and 0 as the last two parameters. 

To create the label widget, the application provides values for the label’s x, y and label 
resources by passing a list of name-value pairs. XtSetArg is used to create this list in a stylized 
coding metaphor that makes it easier to add, delete, or change the settings in the code without 
making mistakes. XtCreateManagedWidget creates a new widget, called “label,” using box as 
its parent and the assigned resources to override default values. 

The application creates the command widget similarly, then attaches the callback procedure 
Callback to it using XtAddCallback. When the command button is activated, the toolkit calls 
Callback and the program terminates. 

6. How a Widget Writer Sees the World 

Sometimes an application writer needs to write a new widget. It will often be a slight variation 
on an existing widget, but can be something completely different. In either case, the toolkit allows 
the writer to ignore parts the new widget has in common with an existing widget and concentrate 
on the differences. 

To accomplish this, the toolkit supports a single-inheritance class hierarchy. Each widget type 
is a class with a single superclass and possibly many subclasses. A subclass contains both the 
declarations of its superclass and data and routines to implement its additional functionality. A 
subclass can inherit procedures (often called “methods”) from its superclass or can implement 
equivalent semantics itself. Any operation that is valid for a class is valid for all subclasses. 

Figure 6-1 shows an abbreviated class hierarchy of the widget set distributed by Project 
Athena. The toolkit intrinsics define the four special classes Core, Composite, Constraint, and 
Shell. All other classes are implemented as direct or indirect subclasses of these. 

The top of the class hierarchy is the Core widget, which contains declarations and code that 
are common to all widgets. It declares the parent widget pointer, name, size and position, 
background, and border color, and defines the methods to maintain this data. 

The Composite widget is the superclass for widgets that can contain children. It contains 
methods for adding and deleting children and for negotiating with them about size and placement. 

The Constraint widget is the superclass for composite widgets that maintain extra contraints 
on a per-child basis. For example, many constraint subclasses keep minimum and maximum 
allowable sizes for each child. 

The Shell widget provides the interface between the internally consistent, cached world of the 
toolkit and the external world of X windows. Shell widgets communicate with the window 
manager and are are used to “pop up” other widgets like menus and dialog boxes. 
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Figure 6-1 : The class tree for the Project Athena widget set. 

To create a new widget class, a programmer first looks at the existing class hierarchy to 
determine if something similar already exists. If the new widget is similar to an existing widget he 
creates a subclass of that widget; otherwise he creates a direct subclass of Core, Composite, or 
Constraint; 

The widgets below show both types of subclass. Label is a subclass of Core and requires 
many lines of declarations and code. Command is just like Label, but adds a pinch of extra 
semantics. It is a subclass of Label and requires relatively little code — most of its functionality is 
inherited from Label. 

7. A Simple Label Widget 

A widget definition is split into three files: a public header file containing information needed to 
use the widget, a private header file containing information needed to subclass the widget, and an 
implementation file with the code that defines the widget’s behavior. 

#define XtNforeground "foreground" 

#define XtNIabel "label" 

#define XtNfont "font" 

typedef struct _LabelRec 'LabelWidget; 
extern WidgetClass labelWidgetClass; 

Figure 7-1 : Label. h: The label public header file 

Figure 7-1 shows the public header file for Label. It defines the names of the three resources 
label adds to Core, XtNforeground, XtNIabel, and XtNfont, a type definition for label widget 
instances, and an external declaration for the class, used in XtCreateManagedWidget. 

Figure 7-2 is the private header file for Label and contains the class and instance data 
structure declarations. Label’s class structure consists of the Core class part, included in all 
widgets, and label’s own class part. Label’s class part needs no extra information, but since the 
C compiler cannot handle empty structures it has a make_compiler_happyi\e\d. 

The label part record has the fields needed for each label instance. The fields foreground, font, 


















#include "Label. h" 


typedef struct { 

int make_compiler_happy; 

} LabelClassPart; 

typedef struct _LabelClassRec { 
CoreClassPart core_class; 

LabelClassPart label_class; 

} LabelClassRec, *LabelWidgetClass; 

extern LabelClassRec labelClassRec; 

typedef struct { 

Pixel 

XFontStruct 
char 
GC 

Dimension 
int 

} LabelPart; 

typedef struct _LabelRec { 

CorePart core; 

LabelPart label; 

} LabelRec; 

#define WIDTH_PAD 4 
#define HEIGHT_PAD 2 


foreground; 

*font; 

*label; 

normal_GC; 

label_width, label_height; 
label Jen; 


Figure 7-2: LabelP.h: The label private header file 

and label correspond to the resources defined in the public header file. The other fields are 
derived by the widget implementation and are described later. All label instances get a complete 
LabelRec consisting of the core fields common to all widgets and the special fields used by label. 

Figure 7-3 is the implementation of Label. Its header files include “IntrinsicP.h,” the intrinsics 
header file for widget programmers, and “LabelP.h,” the label private header file. 

The resources array contains the definitions for the label-specific resources. Each entry 
contains, among other things, the resource name (XtNforeground), its type (XtRPixel), its offset 
in the widget record (XtOffset(...)), its default value (“Black”), and the type of its default 
(XtRString). The intrinsics initializes new records with these defaults unless the values are 
overridden in the argument list passed to the creation routine or in the user preferences file. 

The next part is the initializer for label’s class record. The superclass field is the address of the 
class record for Label’s superclass. The class initialization procedures do any initialization code 
specific to this class; since label has none these are NULL. The initialize procedure is called to 
initialize label widget instances. Realize gets called to create the widget’s window; here it gets 
inherited from its superclass because label doesn’t do anything special. The resources and 
num_resources fields describe label’s resource list. Destroy, resize, and expose are called when 
the widget is destroyed, resized, or needs redisplay. The set_values procedure gets called when 
the application tries to change any of the widget’s state. 

The two routines SetTextWidthAndHeight and GetNormalGC are internal routines to 
maintain the derived fields in the widget record. 

When the application creates a new label widget, the intrinsics call Initialize. It uses the label’s 
name as the text to be displayed if none was provided. After computing the derived fields, it 
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#include <stdio.h> 

#include <string.h> 

#include "IntrinsicP.h" 

#include "LabelP.h" 

#include "Atoms.h" 

static XtResource resourcesQ = { 

{XtNforeground, XtCForeground, XtRPixel, sizeof(Pixel), XtOffset( Label Widget, label.foreground), XtRString, "Black"}, 
{XtNfont, XtCFont, XtRFontStruct, sizeof(XFontStruct *), XtOffset( Label Widget, label.font), XtRString, "fixed"}, 
{XtNIabel, XtCLabel, XtRString, sizeof (String), XtOffset( Label Widget, label.label), XtRString, NULL}, 

}; 




static void lnitialize(), Redisplay(), Destroy(); 
static Boolean SetValues(); 


LabelClassRec labelClassRec = { 


{ 

f* superclass 7 

r class_name 7 

P widget_size 7 

r classjnitialize 7 

r class_part_initialize 7 
I* classjnited 7 

r initialize 7 

r initialize_hook 7 

/* realize 7 

I* actions 7 

/* num_actions 7 

r resources 7 

r num_resources 7 

P xrm_class 7 

r input flags 7 

I* destroy 7 

I* resize 7 

r expose 7 

r set_values 7 

I* set_values_hook 7 

I* set_values_almost 7 
t* get_values_hook 7 

r accept_focus 7 

I* version 7 

r callback offsets 7 

r tm_table 7 


(WidgetClass) &widgetClassRec, 
"Label", 

sizeof(LabelRec), 

NULL, 

NULL, 

FALSE, 

Initialize, 

NULL, 

XtlnheritRealize, 

NULL, 

0 , 

resources, 

XtNumber(resources), 

NULLQUARK, 

TRUE, TRUE, TRUE, FALSE, 
Destroy, 

XtlnheritResize, 

Redisplay, 

SetValues, 

NULL, 

XtlnheritSetValuesAlmost, 

NULL, 

NULL, 

XtVersion, 

NULL, 

NULL, 


} 

}; 


WidgetClass labelWidgetClass = (WidgetClass) &labelClassRec; 

static void SetTextWidthAndHeight(lw) 

LabelWidget Iw; 

{ 

lw->label.labeljen = strlen(lw->label. label); 

lw->label.label_height = lw->label.font->max_bounds. ascent + lw->label.font->max_bounds. descent; 
lw->label.label_width = XTextWidth(fs, lw->label.label, lw->label.label_len); 

} 


static void GetNormalGC(lw) 

LabelWidget Iw; 

{ 

XGCValues values; 

values.foreground = lw->label. foreground; 
values.font = lw->label.font->fid; 

lw->label.normal_GC = XtGetGC((Widget) Iw, GCForeground | GCFont, &values); 

} 

v 


Figure 7-3: Label.c: The label implementation file, part 1 



9 


static void lnitialize(request, new) 

Widget request, new; 

{ 

LabelWidget Iw = (LabelWidget) new; 

if (lw->label. label == NULL) lw->label.label = strcpy(XtMalloc(strIen(lw->core.name) + 1), lw->core.name); 

GetNonmalGC(lw); 

SetTextWidthAndHeight(lw); 

if (lw->core. width == 0) lw->core.width = lw->label.label_width + 2 * WIDTH_PAD; 
if (lw->core.height == 0) lw->core.height = lw->label.label_height + 2 * HEIGHT_PAD; 

} 


static void Redisplay(w, event) 

Widget w; 

XEvent ‘event; 

{ 

LabelWidget Iw = (LabelWidget) w; 

XDrawString(XtDisplay(w), XtWindow(w), lw->label.normal_GC, WIDTH_PAD, 

HEIGHT_PAD + lw->label.font->max_bounds.ascent, lw->label. label, lw->label.label_len); 

} 

static Boolean SetValues(old, request, new) 

Widget old, request, new; 

{ 

LabelWidget oldlw = (LabelWidget) old, newlw = (LabelWidget) new; 
if (newlw->label. label == NULL) newlw->Iabel.label = newlw->core.name; 

if ((urlw->label.label != newlw->label.label || oldlw->label.font != newlw->label.font) SetTextWidthAndHeight(newlw); 
if (oldlw->label.label != newlw->label.label) { 

if (newlw->label.label != NULL) newlw->label.label = strcpy(XtMalloc(newlw->label.labelJen+1), newlw->label. label); 
XtFree((char *) oldlw->label. label); 

if (old!w->core.width == newlw- >core. width) newlw->core.width = newlw->label.label_width + 2 * WIDTH_PAD; 
if (oldlw->core. height == newlw->core. height) newlw->core. height = newlw->label.label_height + 2 * HEIGHT_PAD* 

} 

if (oldlw->label.foreground != newlw->label. foreground || oldlw->label.font->fid != newlw->label.font->fid) { 
GetNormalGC(newlw); 

XtDestroyGC(oldlw->label.normal_GC); 

} 

return TRUE; 

} 

static void Destroy(w) 

Widget w; 

{ 

LabelWidget Iw = (LabelWidget) w; 

XtDestroyGC(lw->label.normal_GC); 

XtFree(lw->label.label); 

XFreeFontlnfo((char **) NULL, lw->label.font, 0); 

} 


Figure 7-3, continued 

checks if the application specified the label’s width or height and if not computes appropriate 
values based upon the size of the label text. 

Redisplay displays the label text by calling XDrawString. 

SetValues is called when the application changes the contents of Label. Its arguments include 
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old, the widget as it is now, and new, a copy of the widget with the requested changes. 
SetValues must make new a consistent widget by updating all derived fields, allocating storage 
for changed pointer fields, and freeing the storage for old pointer values. 

It again uses the name for the text if necessary. If the text or font has changed, SetValues 
recomputes the text dimensions. If the label text has changed, it allocates a copy of the text, 
frees the old storage, and, unless the user has specifically overridden the size, recomputes the 
widget size. Finally it creates a new graphics context and destroys the old one if the foreground 
or font has changed. 

The last routine, Destroy, gets called when a label widget is destroyed and frees all the 
allocated storage associated with it. 



8. A Simple Command Widget 

Command is quite similar to Label, and so needs only a bit of extra code. Its public and 
private header files, Figures 8-1 and 8-2 are analogous to those for Label. 

typedef struct _CommandRec ‘CommandWidget; 
extern WidgetClass commandWidgetClass; 

Figure 8-1 : Command. h: The command button public header file 

#include "Command.h" 

typedef struct _CommandClass { 
int make_compiler_happy; 

} CommandClassPart; 

typedef struct _CommandClassRec { 

CoreClassPart core_class; 

Label Class Part label_class; 

CommandClassPart command_class; 

} CommandClassRec, ‘CommandWidgetClass; 

extern CommandClassRec CommandClassRec; 

typedef struct { 

XtCallbackList callbackjist; 

} CommandPart; 

typedef struct _CommandRec { 

CorePart core; 

Label Part label; 

CommandPart command; 

} CommandRec; 


Figure 8-2: CommandP.h: The command button private header file 

Figure 8-3 is the implementation of the command widget. 

Some widget class information is chained by the intrinsics, meaning that the intrinsics 
automatically use information in the superclass to supplement information in the superclass. The 
resource list is chained data: a subclass has all its superclass’s resources in addition to its own. 
Initialize , set_values } and destroy are chained procedures: the superclass’s corresponding 
procedure is called in addition to the subclass’s. Chained procedures are never explicitly 
inherited; if a class has nothing to add to its parent it just specifies NULL. The command widget 
has NULL initialize and set_values procedures, and adds its own destroy procedure to label’s. 

The intrinsics do not automatically call superclass procedures for unchained operations like 
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#include <stdio.h> 

#include "IntrinsicP.h" 

#include M LabelP.h" 

#include "CommandP.h" 

#include "Atoms. h" 

static XtResource resources^ = { 

{XtNcallback, XtCCallback, XtRCallback, sizeof(caddr_t), 

XtOffset(CommandWidget, command.callbackjist), XtRCallback, (caddr_t) NULL}, 

}; 

static void hJpttfyO, Destroy(); 

static char translations}] = "<Button1Down>: 

static XtActionsRec actionsListQ = { {"notify", 

CommandClassRec commandClassRec = { 

{ 


/* superclass 

V 

(WidgetClass) &labe!ClassRec, 

r c!ass_name 

V 

"Command", 

/* widget_size 

*/ 

sizeof(CommandRec), 

/* classjnitialize 

V 

NULL, 

r class_part_initialize 

V 

NULL, 

r classjnited 

V 

FALSE, 

r initialize 

V 

NULL, 

r initialize_hook 

V 

NULL, 

r realize 

V 

XtlnheritRealize, 

r actions 

V 

actionsList, 

t* num_actions 

V 

XtNumber(actionsList), 

/* resources 

V 

resources, 

P num_resources 

V 

XtNumber( resources), 

/* xrm_class 

V 

NULLQUARK, 

r input flags 

V 

TRUE, TRUE, TRUE, FALSE, 

r destroy 

V 

Destroy, 

r resize 

7 

XtlnheritResize, 

r expose 

7 

XtlnheritExpose, 

r set_values 

7 

NULL, 

/* set_values_hook 

7 

NULL, 

r set_values_almost 

7 

XtlnheritSetValuesAlmost, 

r get_values_hook 

7 

NULL, 

r accept_focus 

7 

NULL, 

r version 

7 

XtVersion, 

r callback offsets 

7 

NULL, 

r tm_table 

7 

translations, 


} 

}; 


notify() M ; 
Notify} }; 


WidgetClass commandWidgetClass = (WidgetClass) &commandClassRec; 

static void Notify(w, event) 

Widget w; 

XEvent 'event; 

{ 

XtCallCallbacks(w, XtNcallback, NULL); 

} 

static void Destroy(w) 

Widget w; 

{ 

XtRemoveAIICallbacks(w, XtNcallback); 

} 


Figure 8-3: Command. c: The command button implementation file 
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Chapter 1 
X Toolkit Overview 


The X Toolkit provides the base functionality necessary to build a variety of application environ- 
ments. The X Toolkit is extensible and supportive of the independent development of new or 
extended components. This is accomplished by defining interfaces that mask implementation 
details from both application and component implementors. By following a small set of conven- 
tions, a programmer can extend the X Toolkit and have these extensions function with existing 
facilities. 

The X Toolkit is a library package layered on top of the X Window System. This layer extends 
the basic abstractions provided by X and provides the next layer of functionality primarily by 
supplying: 

• Mechanisms for interactions between and within user-interface components 

• A cohesive set of sample widgets 

In the X Toolkit, a widget is the combination of an X window or subwindow and its associated 
input and output semantics. 

To the extent possible, the X Toolkit is policy free. The application environment, not the X 
Toolkit, defines, implements, and enforces: 

• Policy 

® Consistency 

• Style 

Each individual widget implementation defines its own policy. The X Toolkit design allows for 
but does not necessarily encourage the free mixing of radically differing widget implementations. 

Note 

This document describes the “Athena Widgets” set. Related future documents may 
describe other widget sets as they are made available. 


1.1. Introduction to the X Toolkit Library 

The X Toolkit library provides tools that simplify the design of application user interfaces in the 
X Window System programming environment. It assists application programmers by providing a 
set of common underlying user-interface functions. It also lets widget programmers modify 
existing widgets or add new widgets. By using the X Toolkit library in their applications, pro- 
grammers present a similar user interface across applications to all workstation users. 

The X Toolkit consists of: 

• A set of Intrinsic mechanisms for building widgets 

• An architectural model for constructing widgets 

• A sample interface (widget set) for programming 

The Intrinsic mechanisms are intended for the widget programmer. The architectural model lets 
the widget programmer design new widgets by using the Intrinsics and by combining other widg- 
ets. The application interface layers built on top of the X Toolkit include a coordinated set of 
widgets and composition policies. Some of these widgets and policies are application domain- 
specific, while others are common across a number of application domains. 
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The X Toolkit library provides an architectural model that can accommodate different kinds of 
application interface layers. In addition, the supplied toolkit functions are: 

• Functionally complete and policy free 

• Stylistically and functionally consistent with the X Window System primitives 

• Portable across languages, computer architectures, and operating systems 
The X Toolkit library also can implement one or more application interface layers to: 

• Verify the toolkit architecture 

• Provide a base set of widgets and composition policies that can be incorporated in other 
application interface layers 

• Make the X Toolkit immediately usable by those application programmers who find that a 
supplied application interface layer meets their needs 

The remainder of this chapter discusses the X Toolkit: 

• Terminology 

e Model 

© Design principles and philosophy 

1.2. Terminology 

The following terms are used throughout this manual. 

Application programmer 

A programmer who uses X Toolkit widgets to produce an application user interface. 

Child 

A widget that is contained in another widget (parent). 

Class 

The general group that a specific object belongs to. 

Client 

A routine that uses a widget in an application or for composing another widget. 

Full name 

The name of a widget instance appended to the full name of its parent. 

Instance 

A specific widget object as opposed to a general widget class. 

Method 

The functions or procedures that a widget itself implements. 

Name 

The name that is specific to an instance of a widget for a given client. 

Object 

A software data abstraction consisting of private data and private and public routines that 
operate on the private data. Users of the abstraction can interact with the object only 
through calls to the object’s public routines. 

Parent 

A widget that contains at least one other widgets (child). A parent widget is also known as 
a composite widget. 

Resource 

A named piece of data in a widget that can be set by a client, by an application, or by user 
defaults. 
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Superclass 

A larger class of which a specific class is a member. All members of a class also are 
members of the superclass. 

User 

A person interacting with a workstation. 

Widget 

An object providing a user interface abstraction (for example, a Scrollbar widget). 

Widget class 

The general group that a specific widget belongs to, which is also known as the type of the 
widget. 

Widget programmer 

A programmer who adds new widgets to the X Toolkit. 

1.3. Underlying Model 

The underlying architectural model is based on the following premises: 

Widgets are X windows 

Every user-interface widget is contained in a unique X window. The X window ID for a 
widget is readily available from the widget ID, so standard Xlib window manipulation pro- 
cedures can operate on widgets. 

Information hiding 

The data for every widget is private to the widget. That is, the data is neither directly acces- 
sible nor visible outside of die module implementing the widget. All program interaction 
with the widget is performed by a set of operations (methods) that are defined for the widg- 
et. 

Widget semantics and widget layout geometry 

Widget semantics are clearly separated from widget layout geometry. Widgets are con- 
cerned with implementing specific user-interface semantics. They have little say over is- 
sues such as their size or placement relative to other widget peers. Mechanisms are provid- 
ed for associating geometric managers with widgets and for widgets to make suggestions 
about their own geometry. 

1.4. Design Principles and Philosophy 

The X Toolkit follows two design principles throughout, which cover languages and language 
bindings as well as widget IDs. 

Languages and Language Bindings 

The X Toolkit facilitates access from objective languages. However, the X Toolkit library is con- 
veniently usable by application programs written in nonobjective languages. Procedural interface 
guidelines are required when the X Toolkit is used with nonobjective languages. 

The guidelines for the procedural interfaces are: 
o Strings are passed as null-terminated character arrays. 

• Most other arrays are passed using two parameters: a size and a pointer to the first element. 

This also applies to argument lists passed to widgets. 

® Most numeric arguments are passed by value. 

® Structures as arguments are avoided, unless a method for building them is provided for 
languages without pointers. Pointers embedded in structures are allowed, but they should 
be avoided if an equivalent alternative is available. 
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• Pointers are not recommended as return arguments, unless they will never have to be 
dereferenced by the caller. If they need to be dereferenced, the caller should allocate 
storage and pass the address to the procedure to fill in. 

• Procedures can be passed as parameters. 

• The ownership of dynamically allocated storage is determined on a case-by-case basis. 

The application is also permitted to replace the standard memory allocation and freeing 
routines used by the library. 

Widget IDs 

All references to widgets are made using a unique identifier that is known as the widget ID. The 
widget ID is returned to the client by the XtCreateWidget function. From an application 
programmer’s perspective, a widget ID is an opaque data type; no particular interpretation may 
be assigned to it. Given a widget ID, the corresponding X window ID, the Display and Screen 
stmctures, and other information are readily available by using Intrinsic functions. 

From a widget programmer’s perspective, the widget ID actually is a pointer to a data structure 
that is known as the widget instance record. Several parts of the data structure are common to all 
widget types, while other parts are unique to a particular widget type. The widget’s private data 
that is associated with a particular widget instance normally is included directly in the widget 
instance record. 
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Widgets serve as the primary tools for building a user interface or application environment. The 
widget set consists of primitive widgets (for example, a command button) and composite widgets 
(for example, a Dialog widget). 

The remaining chapters of this guide explain the widgets and the geometry managers that work 
together to provide a set of user-interface components. These user-interface components serve as 
a default interface for application programmers who do not want to implement their own widgets. 
In addition, they serve as examples or a starting point for those widget programmers who, using 
the Intrinsic mechanisms, want to implement alternative application programming interfaces. 

The remainder of this chapter discusses the common features of the X Toolkit widgets. 

2.1. Initializing the Toolkit 

You must invoke the toolkit initialization function Xtlnitialize prior to invoking any other toolkit 
routines. Xtlnitialize opens the X server connection, parses standard parts of the command line, 
and creates an initial widget that is to serve as the root of a tree of widgets that will be created by 
this application. 

Widget Xtlnitialize(^/2e//_name, application _class, options, numjoptions, argc, argv ) 

String shell jiame\ 

String application _class\ 

XrmOptionDescRec options[]; 

Cardinal num_options\ 

Cardinal *argc\ 

String argv[\, 

shelljiame Specifies the name of the application shell widget instance, which usually is 
something generic like “main”. 

application _class 

Specifies the class name of this application, which usually is the generic name for 
all instances of this application. By convention, the class name is formed by rev- 
ersing the case of the application’s first two letters. For example, an application 
named “xterm” would have a class name of “XTerm”. 

options Specifies how to parse the command line for any application-specific resources. 

The options argument is passed as a parameter to XrmParseCommand. For 
further information, see Xlib - C Language X Interface. 

numjoptions Specifies the number of entries in options list. 

argc Specifies a pointer to the number of command line parameters. 

argv Specifies the command line parameters. 

For further information about this function, see the X Toolkit Intrinsics - C Language X Inter- 
face. 

2.2. Creating a Widget 

Creating a widget is a three-step process. First, the widget instance is allocated, and various 
instance-specific attributes are set by using XtCreateWidget. Second, the widget’s parent is 
informed of the new child by using XtManageChild. Finally, X windows are created for the 
parent and all its children by using XtRealizeWidget and specifying the top-most widget. The 
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first two steps can be combined by using XtCreateManagedWidget. In addition, XtReal- 
izeWidget is automatically called when the child becomes managed if the parent already is real- 
ized. 

To allocate and initialize a widget, use XtCreateWidget. 

Widget XtCreateWidget( name, widget_class, parent, args, num_args) 

String name ; 

WidgetClass widgetjclass'. 

Widget parent, 

ArgList args\ 

Cardinal num_args; 

name Specifies the instance name for the created widget that is used for retrieving 

widget resources. 

widget_class Specifies the widget class pointer for the created widget 
parent Specifies the parent widget ID. 

args Specifies the argument list. The argument list is a variable-length list composed 

of name and value pairs that contain information pertaining to the specific widget 
instance being created. For further information, see “Creating Argument Lists”. 

num_args Specifies the number of arguments in the argument list. When the num_args is 
zero, the argument list is never referenced. 

When a widget instance is successfully created, the widget identifier is returned to the applica- 
tion. If an error is encountered, the XtError routine is invoked to inform the user of the error. 

For further information, see the X Toolkit Intrinsics - C Language X Interface. 

Common Arguments in the Widget Argument List 

Although a widget can have unique arguments that it understands, all widgets have common 
arguments that provide some regularity of operation. The common arguments allow arbitrary 
widgets to be managed by higher-level components without regards to the individual widget type. 
All widgets ignore any argument that they do not understand. 

The following resources are retrieved from the argument list or from the resource database by all 
X Toolkit widgets: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Width of the border in pixels 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callback for XtDestroyWidget 

XtNheight 

int 

widget-dependent 

Height of the widget 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget should receive input 

XtNtranslations 

TranslationT able 

none 

event-to-action translations 

XtNwidth 

int 

widget-dependent 

Width of the widget 

XtNx 

int 

0 

x coordinate within parent 

XtNy 

int 

0 

y coordinate within parent 

The following additional resources are retrieved from the argument list or from the resource data- 

base by many X Toolkit widgets: 



Name 

Type 

Default 

Description 

XtNcallback 

XtCallbackList 

NULL 

Callback functions and client data 
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Name 

Type 

Default 

Description 

XtNforeground 

Pixel 

Black 

Foreground color 


2.3. Realizing a Widget 

The X Toolkit provides the application programmer with a single function that: 

• First, creates an X window for the widget and, if it is a composite widget, for each of its 
managed children. 

• Then, maps each window onto the screen. 

void XtRealizeWidgetOv) 

Widget w; 


w Specifies the widget. 

For further information about this function, see the X Toolkit Intrinsics - C Language X Inter- 
face. 

2.4. Standard Widget Manipulation Functions 

After a widget has been created, a client can interact with that widget by calling: 

• One of the standard widget manipulation routines that provide functions that all widgets 
support 

• A widget class-specific manipulation routine 

The X Toolkit provides generic routines to provide the application programmer access to a set of 
standard widget functions. These routines let an application or composite widget manipulate 
widgets without requiring explicit knowledge of the widget type. The standard widget manipula- 
tion functions let you: 

• Control the location, size and mapping of widget windows 

• Control the screen updating process 

• Destroy a widget instance 

• Obtain an argument value 

• Set an argument value 

Mapping Widgets 

By default, widget windows automatically are mapped (made viewable) by XtRealizeWidget. 
This behavior can be changed by using XtSetMappedWhenManaged , and it then is the client’s 
responsibility to use the XtMapWidget function to make the widget viewable. 

void XtSetMappedWhenManagedOv, map jwhenjnanaged) 

Widget w; 

Boolean mapjwhenjnanaged, 

w Specifies the widget. 

map jwhenjnanaged 

Specifies the new value. If map_when_managed is T rue, the widget is mapped 
automatically when it is realized. If map_when_managed is False, the client 
must call XtMapWidget or make a second call to XtSetMappedWhen- 
Managed to cause the child window to be mapped. 
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The definition for XtMapWidget is: 

XtMapWidget(w) 

Widget w; 

w Specifies the widget. 

When you create several children in sequence for a common parent after it has been realized, it 
generally is more efficient to construct a list of children as they are created and use 
XtManageChildren to inform their parent of them all at once, instead of causing each child to 
be managed separately. By managing a list of children at one time, the parent can avoid wasteful 
duplication of geometry processing. 

void XtManageChildren(c/u7<irerc, num._child.ren ) 

WidgetList children ; 

Cardinal numchildren; 

children Specifies a list of children to add. 

num_children Specifies the number of children to add. 

If the parent already is visible on the screen, it is especially important to batch updates so that the 
minimum amount of visible window reconfiguration is performed. 

For further information about these functions, see the X Toolkit Intrinsics - C Language X Inter- 
face. 

Destroying Widgets 

To destroy a widget instance of any type, use XtDestroyWidget. 

void XtDestroyWidget(w) 

Widget w; 

w Specifies the widget. 

XtDestroyWidget destroys the widget and recursively destroys any children that it may have, 
including the windows created by its children. After calling XtDestroyWidget, no further refer- 
ences should be made to the widget or to the widget IDs of any children that the destroyed widget 
may have had. 

Retrieving Widget Resource Values 

To retrieve the current value of a resource attribute associated with a widget instance, use XtGet- 

Values. 

void XtGetValues(w, args, num_args ) 

Widget w; 

ArgList args; 

Cardinal num_args; 

w Specifies the widget. 

args Specifies a variable length argument fist of name/address pairs which contain the 

resource name and the address to store the resource value into. The arguments 
and values passed in args are dependent on the widget. The storage for argument 
values which are pointed to by args must be allocated and deallocated by the 
caller. 

num_args Specifies the number of arguments in argument list. 
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The arguments and values passed in the argument list are dependent upon the widget. 

V 

Modifying Widget Resource Values 

To modify the current value of a resource attribute associated with a widget instance, use XtSet- 
Values. 

void XtSetValues(w, args, num_args ) 

Widget w, 

ArgList args'. 

Cardinal num_args\ 

w Specifies the widget. 

args Specifies a variable length argument list of name/value pairs which contain the 

arguments to be modified and their new values. The arguments and values 
passed are dependent on the widget being modified. 

numargs Specifies the number of arguments in the argument list. 

The arguments and values passed in the argument list depend upon the widget being modified. 
Some widgets may not allow certain resources to be modified after the widget instance has been 
created or realized. No notification is given if any part of a XtSetValues request is ignored. 

For further information about these functions, see the X Toolkit Intrinsics - C Language X Inter- 
face. 

Note 

The argument list entry for XtGetValues specifies the address to which the caller 
wants the value copied. The argument list entry for XtSetValues , however, con- 
tains the new value itself if the value is four bytes or less; otherwise, it is a pointer to 
the value. 




2.5. Using the Client Callback Interface 

Widgets communicate changes in their state to their clients by means of a callback facility. The 

format for a client’s callback handler is: 

void CallbackProc(w, client _data, call_data)\ 

Widget w, 
caddr_t client_data\ 
caddr_t call_data\ 

w Specifies widget for which the callback is registered. 

client_data Specifies the arbitrary client-supplied data that the widget should pass back to the 
client when the widget executes the client’s callback procedure. This is a way 
for the client registering the callback to also register client-specific data: a 
pointer to additional information about the widget, a reason for invoking the call- 
back, and so on. It is perfectly normal to have client_data of NULL if all neces- 
sary information is in the widget. 

calljdata Specifies any callback- specific data the widget wants to pass to the client. For 
example, when Scrollbar executes its thumbProc callback list, it passes the 
current position of the thumb in the call_data argument. 

Callbacks can be registered with widgets in one of two ways. When the widget is created, a 

pointer to a list of callback procedure and data pairs can be passed in the argument list to 
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XtCreate Widget. The list is of type XtCallbackList: 
typedef struct { 

XtCallbackProc callback; 
caddr_t client_data; 

} XtCallbackRec, XtCallbackList; 

The callback list must be allocated and initialized prior to calling XtCreate Widget. Once the 
widget is created, the client can change or de-allocate this list; The widget, itself, makes no 
further reference to it. 

The second method for registering callbacks is to use XtAddCallback after the widget has been 
created. 

void XtAddCallback(w, callback name, callback, client_datd) 

Widget w; 

String callback_name\ 

XtCallbackProc callback ; 
caddr_t client _data\ 

w Specifies the widget to add the callback to. 

callbackjiame Specifies the callback list within the widget to append to. 
callback Specifies the callback procedure to add. 

client data Specifies the data to be passed to the callback when it is invoked. 
XtAddCallback adds the specified callback to the list for the named widget. 

All widgets provide a callback list named XtNdestroyCallback where clients can register pro- 
cedures that are to be executed when the widget is destroyed. The destroy callbacks are executed 
when the widget or an ancestor is destroyed. The call_data argument is unused for destroy call- 
backs. 

The X Toolkit Intrinsics provide additional functions for further manipulating a callback list. For 
information about these function, see XtCallCallbacks, XtRemoveCallback, XtRemoveCall- 
backs, and XtRemoveAllCallbacks. in the X Toolkit Intrinsics — C Language X Interface. 

2.6. Programming Considerations 

This section provides some guidelines to set up an application program that uses the X Toolkit. 

Writing Applications 

When writing an application that uses the toolkit, the application needs to perform a standard set 
of steps: 

1. Include <X1 1 /Intrinsic.h > in your application programs. This header file automatically 
includes <X1 1/Xlib.h>, so all Xlib functions also are defined. 

2. Include the widget-specific header files for each widget type that you need to use. For 
example, <X1 1 /Label. h> and <X1 1/Command.h>. 

3. Call the Xtlnitialize function prior to invoking any other toolkit or Xlib functions. For 
further information, see Section 2.1 and the X Toolkit Intrinsics - C Language X Interface. 

4. To pass attributes to the widget creation routines, set up argument lists. In this document, a 
list of valid argument names that start with XtN is provided in the discussion of each 
widget. 

For example, while creating a Command button, an application may provide a label string 
to the Command button, such as “PressSpacesToExit”. The application also should 
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provide a function name that the application calls when the command button is selected. 
For further information, see “Creating Argument Lists”. 

5. When the argument list is set up, create the widget by using the XtCreateWidget function. 
For further information, see Section 2.2 and the X Toolkit Intrinsics — C Language X Inter- 
face. 

6. If the widget has any callback routines, which are usually defined by using the XtNcall- 
back argument or the XtAddCallback function, declare these routines within the applica- 
tion. 

7. After a widget has been created, the widget should be managed by using XtManageChild . 
If there is no manipulation of the widget between XtCreateWidget and XtManageChild, 
you can do this in a single step by using XtCreateManagedWidget. For further informa- 
tion about these functions, see the X Toolkit Intrinsics - C Language X Interface. 

8. Most applications now sit in a loop processing events using XtMainLoop, for example: 

XtCreateManagedWidget(«ame, class, parent, args, num_args ); 

XtReahzeWidget(pa/"e«r); 

XtMainLoopO; 

For information about this function, see the X Toolkit Intrinsics — C Language X Interface. 

9. Link your application with libXaw.a (the Athena widgets), libXt.a (the X Toolkit Intrin- 
sics), and libX.a (the core X library). The following provides a sample command line: 

cc -o application application.c -lXaw — lXt -IX 


Creating Argument Lists 

To set up an argument list for the inline specification of widget attributes, you can use one of the 
three approaches discussed in this section. You should use whichever approach fits the needs of 
the application and you are most comfortable with. In general, argument lists should be kept as 
short as possible to allow widget attributes to be specified through the resource database. When- 
ever a client inserts a specific attribute value in an argument fist, the user is prevented from cus- 
tomizing the behavior of the widget. Resource names in the resource database, by convention, 
correspond to their symbolic names that are used in argument list without the XtN prefix. For 
example, the resource name for XtNforeground is “foreground”. For further information, see 
the X Toolkit Intrinsics - C Language X Interface. 

The Arg structure contains: 

typedef struct { 

String name: 

XtArgVal value; 

} Arg, *ArgList; 


Approach 1 

You can statically initialize the argument list, as in this example: 

static Arg arglist[] = { 

{XtNwidth, (XtArgVal) 400), 

{XtNheight, (XtArgVal) 300}, 

}; 
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This approach makes it easy to add or delete new elements. The XtNumber macro can be used 
to compute the number of elements in the argument list, thus preventing simple programming 
errors. The following provides an example: 

XtCreateWidget(rta/rce, class, parent, args, XtNumber(args)); 

Approach 2 

You can use the XtSetArg macro: 

Arg arglist[10]; 

XtSetArg(arglist[ 1 ] , XtNwidth, 400); 

XtSetArg(arglist[2], XtNheight, 300); 

To make it easier to insert and delete entries, you also can use a variable index, as in this exam- 
ple: 

Arg arglist[10]; 

Cardinal i=0; 

XtSetArg(arglist[i], XtNwidth, 400); i++; 

XtSetArg(arglist[i], XtNheight, 300); i++; 

The i variable can then be used as the argument list count in the widget create function. In this 
example, XtNumber would return 10, not 2, and, therefore, is not useful. 

Note 

You should not use auto-increment or auto-decrement within the first argument to 
XtSetArg . As it is currently implemented, XtSetArg is a macro that dereferences 
the first argument twice. 


Approach 3 

You can individually set the elements of the argument list array, one piece at a time: 

Arg arglist[10]; 
arglist[0].name = XtNwidth; 
arglist[0]. value = (XtArgVal) 400; 
arglist[l].name = XtNheight; 
arglist[l], value = (XtArgVal) 300; 

Also in this example, XtNumber would return 10, not 3, and, therefore, is not useful. 

Approach 4 

Use a mixture of Approaches 1 and 3. The argument list is statically defined but some entries are 
modified at run-time. 

static Arg arglist[] = { 

{XtNwidth, (XtArgVal) 400}, 

{ XtNheight, (XtArgVal) NULL } , 

}; 

arglist[l], value = (XtArgVal) 300; 

In this example, XtNumber can be used, as in Approach 1, for easier code maintenance. 
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Sample Program 

This sample program creates one command button that, when pressed, causes the program to exit. 
This example is a complete program that illustrates: 

• Toolkit initialization 

• Optional command-line arguments 

• Widget creation 

• Callback routines 

#include <stdio Ji> 

#include <X1 1 /Intrinsic .h> 

#include <Xll/Command.h> 

static XrmOptionDescRec options [] = { 

{"-label", "*button.label", XrmoptionSepArg, NULL} 

}; 

Syntax(call) 

char *call; 

{ 

fprintf(stderr, "Usage: %s\n", call); 

} 

void Activate(w, client_data, call_data) 

Widget w; 
caddr_t client_data; 
caddr_t call_data; 

{ 

printf( "button was activated.Vi"); 
exit(O); 

} 

void main(argc, argv) 

unsigned int argc; 
char **argv; 

{ 

Widget toplevel; 

static XtCallbackRec callbacks [] = { 

{ Activate, NULL }, 

{ NULL, NULL }, 

}; 

static Arg args[] = { 

{ XtNcallback, (XtArgVal)callbacks }, 

}; 

toplevel = Xtlnitialize("main", "Demo", options, XtNumber (options), &argc, argv ); 
if (argc != 1) Syntax(argv[0]); 

XtCreateManagedWidget("button",commandWidgetClass,toplevel,args,XtNumber(args)); 

XtRealizeWidget( toplevel); 

XtMainLoopQ; 

} 
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Chapter 3 
Widgets 


This chapter describes the following X Toolkit widgets: 

• Command buttons 

• Labels 

• Text 

• Scrollbars 

• Viewports 

• Boxes 

• VPaned 

• Forms 

• Dialog 

• Grip 

3.1. Command Button Widget 

The Command button widget is a rectangle that contains a text label. When the pointer cursor is 
on the button, its border is highlighted to indicate that the button is available for selection. Then, 
when a pointer button is clicked, the button is selected, and the application’s callback routine is 
invoked. 

The class variable for the Command button widget is commandWidgetClass. 

When creating a Command button widget instance, the following resources are retrieved from the 
argument list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Width of button border 

XtNcallback 

XtCallbackList 

NULL 

Callback for button select 

XtNcursor 

Cursor 

opendot 

Pointer cursor 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNfont 

Fontlnfo* 

fixed 

Label font 

XtNforeground 

Pixel 

Black 

Foreground color 

XtNheight 

int 

text height 

Button height 

XtNhighlightThickness 

int 

2 

Width of border to be highlighted 

XtNinsensitiveB order 

Pixmap 

Gray 

Border when not sensitive 

XtNintemalHeight 

int 

2 

Internal border height for highlighting 

XtNintemalW idth 

int 

4 

Internal border width for highlighting 

XtNjustify 

XtJustify 

XtjustifyCenter 

Type of text alignment 

XtNlabel 

char* 

Button name 

Button label 

XtNmappedWhenManaged 

Boolean 

True 

Whether Xt Map Widget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtNtranslations 

TranslationT able 

none 

event-to-action translations 
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V 




Name 

Type 

Default 

Description 

XtNwidth 

int 

text width 

Button width 

XtNx 

int 

0 

Widget x coordinate 

XtNy 

int 

0 

Widget y coordinate 


XtNheight Specifies the height of the Command widget. The default value 

is the minimum height that will contain: 

XtNintemalheight + height of XtNlabel + XtNintemalHeight 
If the specified height is larger than the minimum, the label 
string is centered vertically. 

XtNinternalHeight Represents the distance in pixels between the top and bottom of 

the label text and the horizontal edges of the Command widget. 
HighlightThickness can be larger or smaller than this value. 

Represents the distance in pixels between the ends of the label 
text and the outer vertical edges of the Command widget. 
HighlightThickness can be larger or smaller than this value. 

Specifies left, center, or right alignment of the label string within 
the Command widget. If it is specified within an ArgList, one of 
the values XtJustifyLeft, XtJustifyCenter, or XtJustify Right 
can be specified. In a resource of type “string”, one of the 
values “left”, “center”, or “right” can be specified. 

Specifies the text string that is to be displayed in the Command 
widget. The default is the widget name of the Command widget. 

Causes the Command widget to display a different border and a 
stippled label string when the Command widget is set to insensi- 
tive. 

XtNwidth Specifies the width of the Command widget. The default value 

is the minimum width that will contain: 

XtNintemalWidth + width of XtNlabel + XtNintemalWidth 
If the width is larger or smaller than the minimum, XtNjustify 
determines how the label string is aligned. 

The Command button widget supports the following actions: 

• Switching the button between the foreground and background colors with set and unset 

• Processing application callbacks with notify 

• Switching the internal border between highlighted and unhighlighted states with highlight 
and unhighlight 

The following are the default translation bindings that are used by the Command button widget: 

<BtnDown>ButtonDownl: set() 

<BtnUp>ButtonDown 1 : notify( ) unset( ) 

<EnterWindow>: highlight( ) 

<LeaveWindow>: unset( ) unhighlight( ) 

To create a Command button widget instance, use XtCreateWidget and specify the class vari- 
able commandWidgetClass. 


XtNintemalWidth 

XtNjustify 

XtNlabel 

XtNsensitive 
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To destroy a Command button widget instance, use XtDestroyWidget and specify the widget ID 
of the button. 

The Command button widget supports two callback lists: XtNdestroyCallback and XtNcall- 
back. The notify action executes the callbacks on the the XtN callback list. The call_data argu- 
ment is unused. 

3.2. Label Widget 

A Label is an uneditable text string that is displayed within a window. The string is limited to 
one line and can be aligned to the left, right, or center of its window. A Label can neither be 
selected nor edited by the user. 

The class variable for the Label widget is labelWidgetClass. 

When creating a Label widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Border width in pixels 

XtNcursor 

Cursor 

None 

Pointer cursor 

XtNdestroyCallback 

XtCallbackLis t 

NULL 

Callbacks for XtDestroyWidget 

XtNfont 

Fontlnfo* 

fixed 

Label font 

XtNforeground 

Pixel 

Black 

Foreground color 

XtNheight 

int 

text height 

Height of widget 

XtNinsensitiveB order 

Pixmap 

Gray 

Border when not sensitive 

XtNinternalHeight 

int 

2 

See note 

XtNinternalWidth 

int 

4 

See note 

XtNjustify 

XtJustify 

XtjustifyCenter 

Type of text alignment 

XtNlabel 

char* 

label name 

String to be displayed 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtNwidth 

int 

text width 

Width of widget 

XtNx 

int 

0 

x coordinate in pixels 

XtNy 

int 

0 

y coordinate in pixels 


XtNheight 


XtNinternalHeight 

XtNinternalWidth 


Specifies the height of the Label widget. The default value is the 
minimum height that will contain: 

XtNintemalheight + height of XtNlabel + XtNinternalHeight 
If the specified height is larger than the minimum, the label 
string is centered vertically. 

Represents the distance in pixels between the top and bottom of 
the label text and the horizontal edges of the Label widget. 

Represents the distance in pixels between the ends of the label 
text and the outer vertical edges of the Label widget. 
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Specifies left, center, or right alignment of the label string within 
the Label widget. If it is specified within an ArgList, one of the 
values Xt Justify Left, XtJustifyCenter, or XtJustifyRight can 
be specified. In a resource of type “string”, one of the values 
“left”, “center”, or “right” can be specified. 

Specifies the text string that is to be displayed in the button. The 
default is the widget name of the Label widget. 

Causes the button to display a different border and a stippled 
label string when the Label widget is set to insensitive. 

Specifies the width of the Label widget. The default value is the 
minimum width that will contain: 

XtNintemal Width + width of XtNlabel + XtNintemalWidth 
If the width is larger or smaller than the minimum, XtNjustify 
determines how the label string is aligned. 

To create a Label widget instance, use XtCreateWidget and specify the class variable 
labelWidgetClass. 

To destroy a Label widget instance, use XtDestroyWidget and specify the widget ID of the 
label. 

The Label widget supports only the XtNdestroyCallback callback list. 

3.3. Text Widget 

A Text widget is a window that provides a way for an application to display one or more lines of 
text. The displayed text can reside in a file on disk or in a string in memory. An option also lets 
an application display a vertical Scrollbar in the Text window, letting the user scroll through the 
displayed text Other options allow an application to let the user modify the text in the window. 

The Text widget is divided into three parts: 

® Source 

• Sink 

• Text widget 

The idea is to separate the storage of the text (source) from the painting of the text (sink). The 
Text widget coordinates the sources and sinks. Clients normally will use AsciiText widgets that 
automatically create the source and sink for the client. A client can, if it so chooses, explicitly 
create the source and sink before creating the Text widget. 

The source stores and manipulates the text. The X Toolkit provides string and disk file sources. 
The source determines what functions may be performed on the text. 

The sink obtains the fonts and the colors in which to paint the text. The sink also computes what 
text can fit on each line. The X Toolkit provides a single font, single color ASCII sink. 

If a disk file is used to display the text, two edit modes are available: 
o Append 

• Read-only 

Append mode lets the user enter text into the window, while read-only mode does not. As the 
text is entered, it is added after the last character in the window, regardless of where the user 
positions the cursor. 


XtNjustify 

XtNlabel 

XtNsensitive 

XtNwidth 
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If a string in memory is used, the application must allocate the amount of space needed. If a 
string in memory is used to display text, three types of edit mode are available: 

• Append-only 

• Read-only 

• Editable 

The first two modes are the same as displaying text from a disk file. Editable mode lets the user 
place the cursor anywhere in the text and modify the text at that position. The text cursor posi- 
tion can be modified by using the key strokes or pointer buttons defined by the event bindings. 
All standard keyboard editing facilities are supported by the event bindings. The following 
actions are supported: 


Cursor Movement 


Delete 


forward-character 

delete-next-character 

backward-character 

delete-previous-character 

forward-word 

delete-next-word 

backward-word 

delete-previous-word 

forward-paragraph 

delete-selection 

backward-paragraph 


beginning-of-line 


end-of-line 

Selection 

next-line 

select-word 

previous-line 

select- all 

next-page 

select-start 

previous-page 

select-adjust 

beginning-of-file 

select-end 

end-of-file 

extend-start 

scroll-one-line-up 

extend-adjust 

scroll-one-line-down 

extend-end 


New Line 

newline-and-indent 

newline-and-backup 

newline 


Miscellaneous 

redraw-display 

insert-file 

do-nothing 


Unkill 


kill-word 

backward-kill-word 

kill-selection 

kill-to-end-of-line 

kill-to-end-of-paragraph 


unkill 

stuff 


Notes 


A page corresponds to the size of the Text window. For example, if the Text win- 
dow is 50 lines in length, scrolling forward one page is the same as scrolling forward 
50 lines. 

The delete binding deletes a text item. The kill binding deletes a text item and puts 
the item in the kill buffer (X buffer 1). 
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3. The unkill binding inserts the contents of the kill buffer into the text at the current 
position. The stuff binding inserts the contents of the select buffer (X buffer 0) into 
the text at the current position. 

The default event bindings for the Text widget are: 
char *defaultTextEventBindings[] = { 


“Ctrl<Key>F: 

forward-character( )\n\ 

<Key>Right: 

forward-character( )\n\ 

Ctrl<Key>B: 

backward -character( )\n\ 

<Key>Left: 

backward-character( )\n\ 

Meta<Key>F: 

forward- word( )\n\ 

Meta<Key>B: 

backward-word( )\n\ 

Meta<Key>]: 

forward-paragraph( )\n\ 

Ctrl<Key>[: 

backward-paragraph( )\n\ 

Ctrl<Key>A: 

beginning-of-line( )\n\ 

Ctrl<Key>E: 

end-of-line( )\n\ 

Ctrl<Key>N: 

next-line( )\n\ 

<Key>Down: 

next-line( )\n\ 

Ctrl<Key>P: 

previous-line( )\n\ 

<Key>Up: 

previous-line()\n\ 

Ctrl<Key>V: 

next-page( )\n\ 

Meta<Key>V : 

previous-page( )\n\ 

Meta<Key>\<: 

beginning-of-file( )\n\ 

Meta<Key>\>: 

end-of-file()\n\ 

Ctrl<Key>Z: 

scroll-one-line-up( )\n\ 

Meta<Key>Z: 

scroll-one-line-down( )\n\ 

Ctrl<Key>D: 

delete-next-character( )\n\ 

Ctrl<Key>H: 

delete-previous-character( )\n\ 

<Key>Num_Lock: 

delete-previous-character( )\n\ 

<Key>Delete: 

delete-previous-character( )\n\ 

<Key>B ackSpace : 

delete-previous-character( )\n\ 

Meta<Key>D: 

delete-next- word( )\n\ 

Meta<Key>H: 

delete -previous-word( )\n\ 

Shift Meta<Key>D: 

kill-word( )\n\ 

Shift Meta<Key>H: 

backward-kill-word( )\n\ 

Ctrl<Key>W: 

kill-selection( )\n\ 

Ctrl<Key>K: 

kill-to-end-of-line( )\n\ 

Meta<Key>K: 

kill-to-end-of-paragraph( )\n\ 

Ctrl<Key>Y : 

unkill()\n\ 

Meta<Key>Y: 

stuff()\n\ 

Ctrl<Key>J: 

newline-and-indent( )\n\ 

<Key>Linefeed: 

newline-and-indent( )\n\ 

Ctrl<Key>0: 

newline-and-backup( )\n\ 

Ctrl<Key>M: 

newline( )\n\ 

<Key>Retum: 

newline( )\n\ 

Ctrl<Key>L: 

redraw-display( )\n\ 

Meta<Key>I: 

insert-file( )\n\ 

<FocusIn>: 

focus- in( )\n\ 

<FocusOut>: 

focus-out( )\n\ 

<BtnlDown>: 

select-start( )\n\ 
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B utton 1 <PtrMoved> : 

<BtnlUp>: 

<Btn2Down>: 

<Btn3Down>: 

Button3<PtrMoved>: 

<Btn3Up>: 

<Key>: 

Shift<Key>: 


extend-adjust( )\n\ 
extend-end( )\n\ 
stuff( )\n\ 
extend-start( )\n\ 
extend-adjust( )\n\ 
extend-end( )\n\ 
insert-char( )\n\ 
insert-char()”; 


A user-supplied resource entry can use application-specific bindings, a subset of the supplied 
default bindings, or both. The following is an example of a user-supplied resource entry that uses 
a subset of the default bindings: 


xmh*Text.translation:\n 

<Key>Right: 

<Key>Left: 

<Meta>F: 

<Meta>B: 

<Meta>]: 

<Ctrl>[: 


forward-character( )\n 
backward-character( )\n 
forward-word( )\n 
backward- word( )\n 
forward-paragraph( )\n 
backward-paragraph( ) 


A Text widget lets both the user and the application take control of the text being displayed. The 
user takes control with the scroll bar or with key strokes defined by the event bindings. The 
scroll bar option places the scroll bar on the left side of the window and can be used with any 
editing mode. The application takes control with procedure calls to the Text widget to: 

• Display text at a specified position 

• Highlight specified text areas 

• Replace specified text areas 

The text that is selected within a Text window is put into buffer 0 (zero) and can be retrieved by 
the application with the Xlib X Fetch Bytes function. All standard selection schemes are sup- 
ported by the event bindings. 

The class variable for the Text widget is textWidgetClass. 

To create a Text string widget, use XtCreate Widget and specify the class variable asciiS- 
tringWidgetClass. 

To create a Text file widget, use XtCreateWidget and specify the class variable asci- 
iDiskWidgetClass. 


Note 

If you want to create an instance of the class textWidgetClass, you must provide a 
source and a sink when the widget is created. The Text widget cannot be instantiated 
without either or both. 


When creating a Text widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 
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Name 

Type 

Default 

Description 

XtNborderWidth 

int 

4 

Border width in pixels 

XtNcursor 

Cursor 

XC_xterm 

Pointer cursor 

XtNdialogHOffset 

int 

10 

Offset of insert file dialog 

XtNdialogVOffset 

int 

10 

Offset of insert file dialog 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNdisplayPosition 

int 

0 

Byte offset of first line 

XtNeditType 

XtEditType 

XttextRead 

Edit mode (see note) 

XtNfile 

char* 

tmpnam() 

File name for 
asciiDiskWidgetClass 

XtNforeground 

Pixel 

Black 

Foreground color 

XtNfont 

Fontlnfo* 

fixed 

Fontname 

XtNheight 

int 

font height 

Height of widget 

XtNinsertPosition 

int 

0 

Byte offset of cursor position 

XtNleftMargin 

int 

2 

Left margin in pixels 

XtNIength 

int 

string length 

Length for asciiStringWidgetClass 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNmax Length 

int 

1024 

Maximum string size for 
asciiStringWidgetClass 

XtNselectTypes 

XtTextSelectType* 

See below 

See below 

XtNselection 

XtTextBlock 

none 

String that is highlighted 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtNstring 

char* 

blank 

String for asciiStringWidgetClass 

XtNtextOptions 

int 

none 

See below 

XtNtextSink 

XtTextSink 

none 

See below 

XtNtextSource 

XtTextSource 

none 

See below 

XtN translations 

TranslationT able 

none 

event- to -action translations 

XtNwidth 

int 

100 

Width of widget (pixels) 

XtNx 

int 

0 

x coordinate in pixels 

XtNy 

int 

0 

y coordinate in pixels 


Notes 

1. You cannot use XtNeditType, XtNfile, XtNIength, and XtNfont with the 
XtTextSet Values and the XtTextGetValues calls. 

2. The XtNeditType attribute has one of the values XttextAppend, XttextEdit, or 
XttextRead. 

The options for the XtNtextOptions attribute are: 


Option 

editable 

resizeHeight 

resizeWidth 

scroll Horizontal 
scrollOnOverflow 

scrollVertical 

wordBreak 


Description 

Whether or not the user is allowed to modify the text. 

Makes a request to the parent widget to lengthen the window if all the 
text cannot fit in the window. 

Makes a request to the parent widget to widen the window if the text 
becomes too long to fit on one line. 

Puts a scroll bar on the top of the window. 

Automatically scrolls the text up when new text is entered below the bot- 
tom (last) line. 

Puts a scroll bar on the left side of the window. 

Starts newline when word does not fit on current line. 
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Option 


Description 


These options can be ORed together to set more than one at the same time. XtNselectionT ypes 
is an array of entries of type XtTextSelectType and is used for multiclick. As the pointer button 
is clicked in rapid succession, each click highlights the next “type” described in the array. 


XtselectAll 

XtselectChar 

XtselectLine 

XtselectNull 

XtselectParagraph 

XtselectPosition 

XtselectWord 


Selects the contents of the entire buffer. 

Selects text characters as the pointer moves over them. 

Selects the entire line. 

Indicates the end of the selection array. 

Selects the entire paragraph (delimited by newline characters). 
Selects the current pointer position. 

Selects whole words (delimited by whitespace) as the pointer moves 
onto them. 


The default selectType array is: 

{XtselectPosition, XtselectWord, XtselectLine, XtselectParagraph, XtselectAll, XtselectNull} 

For the default case, two rapid pointer clicks highlight the current word, three clicks highlight the 
current line, four clicks highlight the current paragraph, and five clicks highlight the entire text. 

If the timeout value is exceeded, the next pointer click returns to the first entry in the selection 
array. The selection array is not copied by the Text widget. The client must allocate space for 
the array and may not deallocate or change it until the Text widget is destroyed or until a new 
selection array is set. 


Selecting Text 

To enable an application to select a piece of text, use XtTextSetSelection. 
typedef long XtTextPosition; 

void XtT extSetSelection(w, left, right ) 

Widget w; 

XtTextPosition left, right, 
w Specifies the window ID. 

left Specifies the byte offset at which the the selection begins. 

right Specifies the byte offset at which the selection ends. 

This function highlights the text and puts the text into buffer 0 (zero). The text can be retrieved 
by using the Xlib XFetch Bytes call. 


Unhighlighting Text 

To unhighlight previously highlighted text in a window, use XtTextUnsetSelection. 

void XtTextUnsetSelection(w) 

Widget w; 
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Getting Selected Text Byte Positions 

To enable the application to get the byte positions of the selected text, use XtTextGetSelection- 
Pos. 

void XtTextGetSelectionPos(H’, posl,pos2 ) 

Widget w; 

XtTextPosition *posl, *pos2 ; 
w> Specifies the window ID. 

posl Specifies an argument to which the beginning byte offset of the selection is 

returned. 

pos2 Specifies an argument to which the ending byte offset of the selection is returned. 

Replacing Text 

To enable an application to replace text, use XtTextReplace. 

int XtTextReplace(w, start _pos, end _pos, text ) 

Widget w; 

XtTextPosition start _pos, end _pos ; 

XtTextBlock *text; 

w Specifies the window ID. 

start _pos Specifies the starting byte position of the text replacement. 

end jpos Specifies the ending byte position of the text replacement. 

text Specifies the text to be inserted into the file. 

The XtTextBlock structure contains: 
typedef struct { 

int firstPos; 
int length; 
char *ptr; 

} XtTextBlock, *TextBlockPtr, 

The firstPos field is the starting point to use within the ptr field. The value is usually zero. The 
length field is the number of bytes that are transferred from the ptr field. The number of bytes 
transferred is usually the number of bytes in ptr. The XtTextReplace arguments start_pos and 
end_pos represent the text source byte offsets for text that is found in the XtTextBlock struc- 
ture. The characters between start_pos and end_pos are deleted, and the characters that are 
specified by text are inserted in their place. 

The XtTextReplace function has no effect on a read-only, disk-source Text widget. 

Note 

Only ASCII text currently is supported, and only one font may be used for each Text 
widget. 


3.4. Scrollbar Widget 

The Scrollbar widget is a rectangular box that contains a slide region and a thumb (slide bar). A 
Scrollbar can be used alone, as a valuator, or it can be used within a composite widget (for exam- 
ple, a Viewport). A Scrollbar can be aligned either vertically or horizontally. 
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When a Scrollbar is created, it is drawn with the thumb in a contrasting color. The thumb is used 
to scroll the data and to give visual feedback on the percentage of the data visible. 

Each pointer button invokes a specific scrollbar action. That is, given either a vertical or horizon- 
tal alignment, the pointer button actions will scroll or return data as appropriate for that align- 
ment. Pointer button 1 and button 3 do not perform scrolling operations by default. Instead, they 
return the pixel position of the cursor on the scroll region. When pointer button 2 is clicked, the 
thumb moves to the current pointer position. When pointer button 2 is held down and the pointer 
pointer is moved, the thumb moves in the appropriate direction. 

The cursor in the scroll region changes depending on the current action. When no pointer button 
is pressed, the cursor appears as an arrow that points in the direction that scrolling can occur. 
When either pointer button 1 or button 2 is pressed, the cursor appears as a single-headed arrow 
that points in the direction that scrolling can occur. When pointer button 2 is pressed, the cursor 
appears as an arrow that points to the thumb. 

While scrolling is in progress, the application receives notification from callback procedures. For 
both scrolling actions, the callback returns the Scrollbar widget ID, the client_data, and the pixel 
position relative to the current thumb position. For smooth scrolling, the callback routine returns 
the scroll bar window, the client data, and the current relative position of the thumb. When the 
thumb is moved using pointer button 2, the callback procedure is invoked continuously. When 
the thumb is moved using either button 1 or button 2, the callback procedure is invoked only 
when the button is released. 

The class variable for the Scrollbar widget is scrollbarWidgetClass. 

When creating a Scrollbar widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Width of button border 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callbacks for Xt Destroy Widget 

XtNforeground 

Pixel 

Black 

Thumb color 

XtNheight 

int 

See below 

Height of scroll bar 

XtNlength 

int 

None 

major dimension (height of XtorientVertical) 

XtNmappedWhenManaged 

Boolean 

True 

Whether Xt Map Widget is automatic 

XtNorientation 

XtOrientation 

Xtorient V ertical 

Orientation (vertical or horizontal) 

XtN scrollDCursor 

Cursor 

XC_sb_down_arrow 

Cursor for scrolling down 

XtNscrollHCursor 

Cursor 

XC_sb_h_double_arrow 

Idle horizontal cursor 

XtNscrollLCursor 

Cursor 

XC_sb_left_ arrow 

Cursor for scrolling left 

XtNscrollProc 

XtCallbackList 

NULL 

Callback for the slide region 

XtNscrollRCursor 

Cursor 

XC_sb_right_arrow 

Cursor for scrolling right 

XtNscrollUCursor 

Cursor 

XC_sb_up_ arrow 

Cursor for scrolling up 

XtNscroll V Cursor 

Cursor 

XC_sb_v_double_arrow 

Idle vertical cursor 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtNshown 

float 

NULL 

Percentage the thumb covers 

XtN thickness 

int 

14 

minor dimension (height if XtorientHorizontal) 

XtNthumb 

Pixmap 

Grey 

Thump pixmap 

XtNthumbProc 

XtCallbackList 

NULL 

Callback for thumb select 

XtNtop 

float 

NULL 

Position on scroll bar 

XtN translations 

TranslationT able 

none 

event-to- action translations 

XtNwidth 

int 

See below 

Width of scroll bar 

XtNx 

int 

NULL 

x position of scroll bar 

XtNy 

int 

NULL 

y position of scroll bar 


24 



X Toolkit Widgets 


Xll, Release 2 


Name 


Type 


Default 


Description 


You can set the dimensions of the Scrollbar two ways. As for all widgets, you can use the 
XtNwidth and XtNheight resources. In addition, you can use an alternative method that is 
independent of the vertical or horizontal orientation: 

XtN length Specifies the height for a vertical Scrollbar and the width for a horizontal 

Scrollbar. 

XtNthickness Specifies the width for a vertical Scrollbar and the height for a horizontal 

Scrollbar. 

To create a Scrollbar widget instance, use XtCreateWidget and specify the class variable 
scrollbarWidgetClass. 

The callback procedure for the slide area is: 

void ScrollProciscrollbar, client data, position) 

Widget scrollbar, 
caddr_t client data', 
int position', 

scrollbar Specifies the ID of the Scrollbar. 
clientjdata Specifies the client data. 

position Returns the pixel position of the thumb in integer form. 

The Scroll Proc callback is used for incremental scrolling and for getting feedback from the 
thumb and background. The position argument is a signed quantity. Using the default button 
bindings, Button 1 returns a positive value, and Button 3 returns a negative value. In both cases, 
the magnitude of the value is the distance of the pointer from the top (or left) of the Scrollbar. 

The value will never be less than zero or greater than the length of the Scrollbar. 

The callback procedure for the thumb area is: 

void ThumbProc{scrollbar, client data, percent) 

Widget scrollbar, 
caddr_t client _data\ 
float percent', 

scrollbar Specifies the ID of the scroll bar window. 
client data Specifies the client data. 

percent Specifies the floating point position of the thumb (0.0 - 1.0). 

The ThumbProc callback is used to implement smooth scrolling. With the default button bind- 
ings, Button2 moves the thumb interactively, and the ThumbProc is called on each new position 
of the pointer. 

To set the values of a Scrollbar thumb, use XtScrollbarSetThumb. 

void XtScrollbarSetThumb(w, top, shown) 

Widget w; 
float top ; 
float shown'. 


w Specifies the Scrollbar widget ID. 

top Specifies the position of the top of the thumb as a fraction of the length of the 

Scrollbar. 
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shown Specifies the length of the thumb as a fraction of the total length of the Scrollbar. 

XtScrollbarThumb moves the visible thumb to position (0.0 - 1.0) and length (0.0 - 1.0). 

Either the top or shown arguments can be specified as —1.0, in which case the current value is left 
unchanged. Values greater than 1.0 are truncated to 1.0. 

If called from the ThumbProc, XtScrollbarSetThumb has no effect. 

To destroy a Scrollbar widget instance, use XtDestroyWidget and specify the widget ID for the 
Scrollbar. 

3.5. Viewport Widget 

The Viewport widget consists of a frame window, one or two Scrollbars, and an inner window. 
The frame window is determined by the viewing size of the data that is to be displayed and the 
dimensions to which the Viewport is created. The inner window is the full size of the data that is 
to be displayed and is clipped by the frame window. The Viewport widget controls the scrolling 
of the data directly. No application callbacks are required for scrolling. 

When the geometry of the frame window is equal in size to the inner window, or when the data 
does not require scrolling, the Viewport widget automatically removes the Scrollbar(s). The for- 
ceBars option causes the viewport widget to display the Scrollbar(s) permanently. 

The class variable for the Viewport widget is viewportWidgetClass. 

When creating a Viewport widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 


Name 

Type 

Default 

Description 

XtNallowHoriz 

Boolean 

False 

Flag to allow horizontal scroll bars 

XtNallowVert 

Boolean 

False 

Flag to allow vertical scroll bars 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Width of the border in pixels 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callback for XtDestroyWidget 

XtNforceBars 

Boolean 

False 

Flag to force display of scroll bars 

XtNheight 

int 

widget-dependent 

Height of the widget 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget should receive input 

XtNtranslations 

TranslationTable 

none 

event-to-action translations 

XtNuseBottom 

Boolean 

False 

Flag to indicate bottom/top bars 

XtNuseRight 

Boolean 

False 

Flag to indicate right/left bars 

XtNwidth 

int 

widget-dependent 

Width of the widget 

XtNx 

int 

0 

x coordinate within parent 

XtNy 

int 

0 

y coordinate within parent 


The Viewport widget manages a single child widget. When the size of the child is larger than the 
size of the Viewport, the user may interactively move the child within the Viewport by reposi- 
tioning the Scrollbars. 

To create a Viewport widget instance, use XtCreate Widget and specify the class variable 
viewportWidgetClass. 

To insert a child into a Viewport widget, use XtCreateWidget and specify the widget ID of the 
previously created Viewport as the parent. 

To remove a child from a Viewport widget, use XtUnmanageChild or XtDestroyWidget and 
specify the widget ID of the child. 
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To delete the inner window, any children, and the frame window, use XtDestroyWidget and 
specify the widget ID of the Viewport widget. 

3.6. Box Widget 

The Box widget provides geometry management of arbitrary widgets in a box of a specified 
dimension. The children are rearranged when resizing events occurs either on the Box or when 
children are added or deleted. 

The children are arranged on a background that has its own specified dimensions and colors. 
The class variable for the Box widget is boxWidgetClass. 

When creating a Box widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Border width on button box 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNhSpace 

int 

4 

Pixel distance left and right of children 

XtNheight 

int 

NULL 

Viewing height of inner window 

XtNmappedWhenManaged 

Boolean 

True 

Whether Xt Map Widget is automatic 

XtN translations 

TranslationT able 

none 

event-to-action translations 

XtNvSpace 

int 

4 

Pixel distance top and bottom of children 

XtNwidth 

int 

NULL 

Viewing width of inner window 

XtNx 

int 

0 

Widget location x coordinate 

XtNy 

int 

0 

Widget location y coordinate 


The Box widget positions its children in rows with hSpace pixels to the left and right of each 
child and vSpace pixels between rows. If the Box width is not specified, the Box widget uses 
the width of the widest child. After positioning all children, the Box widget attempts to shrink its 
size to the minimum dimensions required for the layout. 

To create a box widget instance, use XtCreate Widget and specify the class variable 
boxWidgetClass. 

To add a child to the Box, use XtCreateWidget and specify the widget ID of the Box as the 
parent.of the new widget. 

To remove a child from the Box, use XtUnmanageChild or XtDestroyWidget and specify the 
widget ID of the child. 

To destroy a Box widget instance, use XtDestroyWidget and specify the widget ID of the Box 
widget. All the children of this box are automatically destroyed at the same time. 

3.7. VPaned Widget 

The VPaned widget manages children in a vertically tiled fashion. A region, called a grip, 
appears on the border between each child. When the pointer pointer is positioned on a grip and 
pressed, an arrow is displayed that indicates the direction the border can be moved While keeping 
the pointer button down, the user can move the pointer in the direction of the arrow. This, in 
turn, changes the window borders, causing one widget to shrink and a neighbor widget to grow. 
The VPaned widget can change the height of all vertical paned windows, which are arranged 
from the top to the bottom of the parent window. 
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The class variable for the VPaned widget is vPanedWidgetClass. 

When creating a Waned widget instance, the following resources are retrieved from the argu- 
ment list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroimdPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Border width (pixels) 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNforeground 

Pixel 

Black 

Pixel value for the foreground color 

XtNheight 

int 

NULL 

Height of vPane 

XtNgripIndent 

int 

16 

Offset of grip from margin (pixels) 

XtNmappedWhenManaged 

Boolean 

True 

Whether Xt Map Widget is automatic 

XtNrefigureMode 

Boolean 

On 

Whether vPane should adjust children 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtN translations 

TranslationT able 

none 

event- to -action translations 

XtNwidth 

int 

NULL 

Width of vPane 

XtNx 

int 

NULL 

x position of vPane 

XtNy 

int 

NULL 

y position of vPane 


To create a Waned widget instance, use XtCreateWidget and specify the class variable 
vPanedWidgetClass. 

Once the parent frame is created, you then add panes to it. Any type of widget can be paned. 

To add a child pane to a Waned frame, use XtCreateWidget and specify the widget ID of the 
Waned widget as the parent of each new child pane. 

When creating a child pane, the following resources, by which the Waned widget controls the 
placement of the child, can be specified in the argument list or retrieved from the resource data- 
base: 


Name 

Type 

Default 

Description 

XtNallowResize 

Boolean 

False 

True if child is allowed to make resize 
requests 

XtNmax 

int 

65535 

maximum height for pane 

XtNmin 

int 

1 

minimum height for pane 

XtNskipAdjust 

Boolean 

False 

True if VPaned widget should not 
automatically resize pane 


To delete a pane from a vertical-paned window frame, use XtUnmanageWidget or XtDes- 
troy Widget and specify the widget ID of the child pane. 

To enable or disable a child’s request for pane resizing, use XtPanedAllowResize. 

void XtPanedAllowResize(w, allow _resize ) 

Widget w; 

Boolean allow _resize; 

w Specifies the widget ID of the child widget pane. 

allow resize Enables or disables a pane window for resizing requests. 

If allow_resize is T rue, Wane allows geometry requests from the child to change the pane’s 
height. If allow jresize is False, Wane ignores geometry requests from the child to change the 
pane’s height. The default state is True before the Wane is realized and False after it is 
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realized. 

To change the minimum and maximum height settings for a pane, use XtPanedSetMinMax. 

void XtPanedSetMinMax(vv, min, max) 

Widget w; 
int min, max; 

w Specifies the widget ID of the child widget pane. 

min New minimum height of the child, expressed in pixels. 

max New maximum height of the child, expressed in pixels. 

To enable or disable automatic recalculation of pane sizes and positions, use 

XtPanedSetRefigureMode. 

void XtPanedSetRefigureMode(w, mode) 

Widget w; 

Boolean mode; 

w Specifies the widget ID of the VPaned widget. 

mode Enables or disables refiguration. 

You should set the mode to FALSE if you add or remove multiple panes to/from the parent frame 
after it has been realized, unless you can arrange to manage all the panes at once using 
XtManageChildren . After all the panes are added, set the mode to TRUE. This avoids 
unnecessary geometry calculations and “window dancing”. 

To delete an entire Waned widget and all associated data structures, use XtDestroyWidget and 
specify the widget ID of the Waned widget. All the children of the Waned widget automati- 
cally are destroyed at the same time. 

3.8. Form Widget 

The Form widget can contain an arbitrary number of children or subwidgets. The Form provides 
geometry management for the subwidgets. Any combination of children can be added to a Fonn. 
When the Form is resized, it computes new positions and sizes for its children. This computation 
is based upon information provided when a child is added to the Form. 

The class variable for a Form widget is formWidgetClass. 

When creating a Form widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

X tNborder W idth 

int 

1 

Width of border in pixels 

XtNdefaultDistance 

int 

4 

Default value for XtNhorizDistance 




and XtNvertDistance 

XtNdes troy Callback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNheight 

int 

10 

Height of form 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtN translations 

TranslationT able 

none 

event- to -action translations 

XtNwidth 

int 

10 

Width of form 

XtNx 

int 

NULL 

x position of form 

XtNy 

int 

NULL 

y position of form 



29 




X Toolkit Widgets 


Xll, Release 2 


Name Type Default Description 


To create a Form widget instance, use XtCreateWidget and specify the class variable 
formWidgetClass. 

To add a new child to a Form, use XtCreateWidget and specify the widget ID of the previously 
created Form as the parent of the child. 

When creating children that are to be added to a Form, the following additional resources are 
retrieved from the argument list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbottom 

XtEdgeType 

XtRubber 

See text 

XtNfromHoriz 

Widget 

NULL 

See text 

XtNfromVert 

Widget 

NULL 

See text 

XtNhorizDistance 

int 

XtdefaultDistance 

See text 

XtNIeft 

XtEdgeType 

XtRubber 

See text 

XtNresizable 

Boolean 

FALSE 

TRUE if allowed to resize 

XtNright 

XtEdgeType 

XtRubber 

See text 

XtNtop 

XtEdgeType 

XtRubber 

See text 

XtNvertDistance 

int 

XtdefaultDistance 

See text 


When a widget is added to a Form, it can, to some extent, specify hints to the form where it 
should be positioned within the form. 

The parameters XtNhorizDistance and XtNfromHoriz let the widget position itself a specified 
number of pixels horizontally away from another widget in the form. As an example, XtNhoriz- 
Distance could equal 10 and XtNfromHoriz could be the widget ID of another widget in the 
Form. The new widget will be placed 10 pixels to the right of the widget defined in 
XtNfromHoriz. If XtNfromHoriz equals NULL, then XtNhorizDistance is measured from the 
left edge of the Form. 

Similarly, the parameters XtNvertDistance and XtNfrom Vert let the widget position itself a 
specified number of pixels vertically away from another widget in the Form. If XtNfromVert 
equals NULL, then XtNvertDistance is measured from the top of the Form. 

The XtNtop, XtN bottom, XtNIeft, and XtNright parameters tell the Form where to position the 
widget when the Form is resized. The XtEdgeType structure contains: 

typedef enum { 

XtChainTop, 

XtChainBottom, 

XtChainLeft, 

XtChainRight, 

XtRubber, 

} XtEdgeType; 

The XtChainTop, XtChainBottom, XtChainLeft, and XtChainRight fields maintain a con- 
stant distance from an edge of the widget to the top, bottom, left, or right edges of a Form. The 
XtRubber field maintains a proportional distance from an edge of a widget to all edges of the 
Form. 

To remove a child from a Form, use XtUnmanageChild or XtDestroyWidget and specify the 
widget ID of the child widget. 

To destroy a Form widget instance, use XtDestroyWidget and specify the widget ID of the 
Form. All children of the Form automatically are destroyed at the same time. 
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3.9. Dialog Widget 

The Dialog widget implements a commonly used interaction semantic to prompt for auxiliary 
input from a user. For example, you can use a Dialog widget when an application requires a 
small piece of information, such as a file name, from the user. Essentially, a Dialog widget is a 
special case of the Form widget that provides a convenient way to create a “preconfigured 
form”. 

The typical Dialog widget contains three areas. The first line contains a description of the func- 
tion of the Dialog widget, for example, the string “Filename:”. The second line contains an area 
into which the user types input. The third line can contain buttons that let the user confirm or 
cancel the Dialog input. 

The class variable for the Dialog box widget is dialog WidgetClass. 

When creating a Dialog widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

White 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

1 

Width of border in pixels 

XtNdestroy Callback 

XtCallbackList 

NULL 

Callbacks for XtDestroyWidget 

XtNheight 

int 

10 

Height of dialog 

XtNlabel 

char* 

label name 

String to be displayed 

XtNmappedWhenManaged 

Boolean 

True 

Whether XtMapWidget is automatic 

XtNmaximumLeng th 

int 

256 

Maximum number of input characters 

XtNsensitive 

Boolean 

True 

Whether widget receives input 

XtNiranslations 

TranslationT able 

none 

event-to-action translations 

XtNvalue 

char* 

NULL 

Pointer to default string 

XtNwidth 

int 

10 

Width of dialog 

XtNx 

int 

NULL 

x position of dialog 

XtNy 

int 

NULL 

y position of dialog 


The instance name of the label for the Dialog widget is ‘ ‘label’ ’ , and the instance name of the 
Dialog value field is “value”. 

To create a Dialog widget instance, you can use XtCreateWidget and specify the class variable 
dialog WidgetClass, or you can use the XtDialogCreate convenience function. 

Widget XtDialogCreatc(/;arcnf, description, valueinit, args, num_args ) 

Widget parent ; 
char * description ; 
char *valueinit; 

ArgList args; 
int numargs; 


parent 

description 

valueinit 

args 


Specifies the widget ID in which the Dialog box is to reside. 

Specifies a pointer to the title for the Dialog box. 

Specifies a pointer to the initial value that is displayed in the Dialog box. Use 
NULL if you do not want a value field. 

Specifies a variable-length argument list. The argument list is the same as that 
for the form widget. 
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num args Specifies the number of arguments in the argument list. When the argument list 
is NULL, the num_args must be zero. However, when the num_args is zero, the 
argument list does not have to be NULL. 

XtDialogCreate is convenience function that calls XtCreateWidget and specifies the class 
dialogWidgetClass. 

To add a child button to the Dialog box, use XtCreateWidget and specify widget ID of the pre- 
viously created Dialog box as the parent of each child. When creating buttons, you do not have 
to specify form constraints. The Dialog box will automatically add the constraints. 

To return the character string in the text field, use XtDialogGetValueString . 

char *XtDialogGetValueString(w) 

Widget w; 

w Specifies the widget ID of the Dialog box. 

To remove a child button from the Dialog box, use XtUnmanageChild or XtDestroyWidget 
and specify the widget ID of the child. 

To destroy a Dialog widget instance, use XtDestroyWidget and specify the widget ID of the 
Dialog widget. All children of the Dialog automatically are destroyed at the same time. 

3.10. Grip Widget 

The Grip widget provides a small region in which pointer events are handled. The most common 
use for the grip is as an attachment point for visually repositioning an object, such as the pane 
border in a VPaned widget. 

The class variable for the Grip widget is gripWidgetCIass. 

When creating a Grip widget instance, the following resources are retrieved from the argument 
list or from the resource database: 


Name 

Type 

Default 

Description 

XtNbackground 

Pixel 

Black 

Window background color 

XtNbackgroundPixmap 

Pixmap 

none 

Window background pixmap 

XtNborderColor 

Pixel 

Black 

Window border color 

XtNborderPixmap 

Pixmap 

none 

Window border pixmap 

XtNborderWidth 

int 

0 

Width of the border in pixels 

XtNcallback 

XtCallbackList 

none 

Action routine 

XtNdestroyCallback 

XtCallbackList 

NULL 

Callback for XtDestroyWidget 

XtNheight 

int 

8 

Height of the widget 

XtNmappedWhenManaged 

Boolean 

True 

Whether Xt Map Widget is automatic 

XtNsensitive 

Boolean 

True 

Whether widget should receive input 

XtNtranslations 

TranslationT able 

none 

event-to-action translations 

XtNwidth 

int 

8 

Width of the widget 

XtNx 

int 

0 

x coordinate within parent 

XtNy 

int 

0 

y coordinate within parent 


The Grip widget does not declare any default event translation bindings, but it does declare a sin- 
gle action routine named “GripAction” in its action table. Using this table, the client specifies 
an arbitrary event translation table giving parameters to the GripAction routine. The GripAction 
is declared in the client program. 

The following is an example of a GripAction table: 

<BtnlDown>: GripAction(press)\n\ 

<BtnlMotion>: GripAction(move)\n\ 

<BtnlUp>: GripAction(release) 
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For a complete description of the format of action routines, see X Toolkit Intrinsics - C Language 
V X Interface. 

To create a Grip widget instance, use XtCreateWidget and specify the class variable 
gripWidgetClass. 

To destroy a Command button widget instance, use XtDestroyWidget and specify the ID of the 
Grip widget. 



